1 /* 2 * v4l2-event.h 3 * 4 * V4L2 events. 5 * 6 * Copyright (C) 2009--2010 Nokia Corporation. 7 * 8 * Contact: Sakari Ailus <sakari.ailus@iki.fi> 9 * 10 * This program is free software; you can redistribute it and/or 11 * modify it under the terms of the GNU General Public License 12 * version 2 as published by the Free Software Foundation. 13 * 14 * This program is distributed in the hope that it will be useful, but 15 * WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * General Public License for more details. 18 * 19 * You should have received a copy of the GNU General Public License 20 * along with this program; if not, write to the Free Software 21 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 22 * 02110-1301 USA 23 */ 24 25 #ifndef V4L2_EVENT_H 26 #define V4L2_EVENT_H 27 28 #include <linux/types.h> 29 #include <linux/videodev2.h> 30 #include <linux/wait.h> 31 32 /* 33 * Overview: 34 * 35 * Events are subscribed per-filehandle. An event specification consists of a 36 * type and is optionally associated with an object identified through the 37 * 'id' field. So an event is uniquely identified by the (type, id) tuple. 38 * 39 * The v4l2-fh struct has a list of subscribed events. The v4l2_subscribed_event 40 * struct is added to that list, one for every subscribed event. 41 * 42 * Each v4l2_subscribed_event struct ends with an array of v4l2_kevent structs. 43 * This array (ringbuffer, really) is used to store any events raised by the 44 * driver. The v4l2_kevent struct links into the 'available' list of the 45 * v4l2_fh struct so VIDIOC_DQEVENT will know which event to dequeue first. 46 * 47 * Finally, if the event subscription is associated with a particular object 48 * such as a V4L2 control, then that object needs to know about that as well 49 * so that an event can be raised by that object. So the 'node' field can 50 * be used to link the v4l2_subscribed_event struct into a list of that 51 * object. 52 * 53 * So to summarize: 54 * 55 * struct v4l2_fh has two lists: one of the subscribed events, and one of the 56 * pending events. 57 * 58 * struct v4l2_subscribed_event has a ringbuffer of raised (pending) events of 59 * that particular type. 60 * 61 * If struct v4l2_subscribed_event is associated with a specific object, then 62 * that object will have an internal list of struct v4l2_subscribed_event so 63 * it knows who subscribed an event to that object. 64 */ 65 66 struct v4l2_fh; 67 struct v4l2_subdev; 68 struct v4l2_subscribed_event; 69 struct video_device; 70 71 /** 72 * struct v4l2_kevent - Internal kernel event struct. 73 * @list: List node for the v4l2_fh->available list. 74 * @sev: Pointer to parent v4l2_subscribed_event. 75 * @event: The event itself. 76 */ 77 struct v4l2_kevent { 78 struct list_head list; 79 struct v4l2_subscribed_event *sev; 80 struct v4l2_event event; 81 }; 82 83 /** struct v4l2_subscribed_event_ops - Subscribed event operations. 84 * 85 * @add: Optional callback, called when a new listener is added 86 * @del: Optional callback, called when a listener stops listening 87 * @replace: Optional callback that can replace event 'old' with event 'new'. 88 * @merge: Optional callback that can merge event 'old' into event 'new'. 89 */ 90 struct v4l2_subscribed_event_ops { 91 int (*add)(struct v4l2_subscribed_event *sev, unsigned elems); 92 void (*del)(struct v4l2_subscribed_event *sev); 93 void (*replace)(struct v4l2_event *old, const struct v4l2_event *new); 94 void (*merge)(const struct v4l2_event *old, struct v4l2_event *new); 95 }; 96 97 /** 98 * struct v4l2_subscribed_event - Internal struct representing a subscribed event. 99 * @list: List node for the v4l2_fh->subscribed list. 100 * @type: Event type. 101 * @id: Associated object ID (e.g. control ID). 0 if there isn't any. 102 * @flags: Copy of v4l2_event_subscription->flags. 103 * @fh: Filehandle that subscribed to this event. 104 * @node: List node that hooks into the object's event list (if there is one). 105 * @ops: v4l2_subscribed_event_ops 106 * @elems: The number of elements in the events array. 107 * @first: The index of the events containing the oldest available event. 108 * @in_use: The number of queued events. 109 * @events: An array of @elems events. 110 */ 111 struct v4l2_subscribed_event { 112 struct list_head list; 113 u32 type; 114 u32 id; 115 u32 flags; 116 struct v4l2_fh *fh; 117 struct list_head node; 118 const struct v4l2_subscribed_event_ops *ops; 119 unsigned elems; 120 unsigned first; 121 unsigned in_use; 122 struct v4l2_kevent events[]; 123 }; 124 125 int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event, 126 int nonblocking); 127 void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev); 128 void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev); 129 int v4l2_event_pending(struct v4l2_fh *fh); 130 int v4l2_event_subscribe(struct v4l2_fh *fh, 131 const struct v4l2_event_subscription *sub, unsigned elems, 132 const struct v4l2_subscribed_event_ops *ops); 133 int v4l2_event_unsubscribe(struct v4l2_fh *fh, 134 const struct v4l2_event_subscription *sub); 135 void v4l2_event_unsubscribe_all(struct v4l2_fh *fh); 136 int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd, struct v4l2_fh *fh, 137 struct v4l2_event_subscription *sub); 138 int v4l2_src_change_event_subscribe(struct v4l2_fh *fh, 139 const struct v4l2_event_subscription *sub); 140 int v4l2_src_change_event_subdev_subscribe(struct v4l2_subdev *sd, 141 struct v4l2_fh *fh, struct v4l2_event_subscription *sub); 142 #endif /* V4L2_EVENT_H */ 143