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 /** 84 * struct v4l2_subscribed_event_ops - Subscribed event operations. 85 * 86 * @add: Optional callback, called when a new listener is added 87 * @del: Optional callback, called when a listener stops listening 88 * @replace: Optional callback that can replace event 'old' with event 'new'. 89 * @merge: Optional callback that can merge event 'old' into event 'new'. 90 */ 91 struct v4l2_subscribed_event_ops { 92 int (*add)(struct v4l2_subscribed_event *sev, unsigned int elems); 93 void (*del)(struct v4l2_subscribed_event *sev); 94 void (*replace)(struct v4l2_event *old, const struct v4l2_event *new); 95 void (*merge)(const struct v4l2_event *old, struct v4l2_event *new); 96 }; 97 98 /** 99 * struct v4l2_subscribed_event - Internal struct representing a subscribed 100 * event. 101 * 102 * @list: List node for the v4l2_fh->subscribed list. 103 * @type: Event type. 104 * @id: Associated object ID (e.g. control ID). 0 if there isn't any. 105 * @flags: Copy of v4l2_event_subscription->flags. 106 * @fh: Filehandle that subscribed to this event. 107 * @node: List node that hooks into the object's event list 108 * (if there is one). 109 * @ops: v4l2_subscribed_event_ops 110 * @elems: The number of elements in the events array. 111 * @first: The index of the events containing the oldest available event. 112 * @in_use: The number of queued events. 113 * @events: An array of @elems events. 114 */ 115 struct v4l2_subscribed_event { 116 struct list_head list; 117 u32 type; 118 u32 id; 119 u32 flags; 120 struct v4l2_fh *fh; 121 struct list_head node; 122 const struct v4l2_subscribed_event_ops *ops; 123 unsigned int elems; 124 unsigned int first; 125 unsigned int in_use; 126 struct v4l2_kevent events[]; 127 }; 128 129 /** 130 * v4l2_event_dequeue - Dequeue events from video device. 131 * 132 * @fh: pointer to struct v4l2_fh 133 * @event: pointer to struct v4l2_event 134 * @nonblocking: if not zero, waits for an event to arrive 135 */ 136 int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event, 137 int nonblocking); 138 139 /** 140 * v4l2_event_queue - Queue events to video device. 141 * 142 * @vdev: pointer to &struct video_device 143 * @ev: pointer to &struct v4l2_event 144 * 145 * The event will be queued for all &struct v4l2_fh file handlers. 146 * 147 * .. note:: 148 * The driver's only responsibility is to fill in the type and the data 149 * fields.The other fields will be filled in by V4L2. 150 */ 151 void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev); 152 153 /** 154 * v4l2_event_queue_fh - Queue events to video device. 155 * 156 * @fh: pointer to &struct v4l2_fh 157 * @ev: pointer to &struct v4l2_event 158 * 159 * 160 * The event will be queued only for the specified &struct v4l2_fh file handler. 161 * 162 * .. note:: 163 * The driver's only responsibility is to fill in the type and the data 164 * fields.The other fields will be filled in by V4L2. 165 */ 166 void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev); 167 168 /** 169 * v4l2_event_pending - Check if an event is available 170 * 171 * @fh: pointer to &struct v4l2_fh 172 * 173 * Returns the number of pending events. 174 */ 175 int v4l2_event_pending(struct v4l2_fh *fh); 176 177 /** 178 * v4l2_event_subscribe - Subscribes to an event 179 * 180 * @fh: pointer to &struct v4l2_fh 181 * @sub: pointer to &struct v4l2_event_subscription 182 * @elems: size of the events queue 183 * @ops: pointer to &v4l2_subscribed_event_ops 184 * 185 * .. note:: 186 * 187 * if @elems is zero, the framework will fill in a default value, 188 * with is currently 1 element. 189 */ 190 int v4l2_event_subscribe(struct v4l2_fh *fh, 191 const struct v4l2_event_subscription *sub, 192 unsigned int elems, 193 const struct v4l2_subscribed_event_ops *ops); 194 /** 195 * v4l2_event_unsubscribe - Unsubscribes to an event 196 * 197 * @fh: pointer to &struct v4l2_fh 198 * @sub: pointer to &struct v4l2_event_subscription 199 */ 200 int v4l2_event_unsubscribe(struct v4l2_fh *fh, 201 const struct v4l2_event_subscription *sub); 202 /** 203 * v4l2_event_unsubscribe_all - Unsubscribes to all events 204 * 205 * @fh: pointer to &struct v4l2_fh 206 */ 207 void v4l2_event_unsubscribe_all(struct v4l2_fh *fh); 208 209 /** 210 * v4l2_event_subdev_unsubscribe - Subdev variant of v4l2_event_unsubscribe() 211 * 212 * @sd: pointer to &struct v4l2_subdev 213 * @fh: pointer to &struct v4l2_fh 214 * @sub: pointer to &struct v4l2_event_subscription 215 * 216 * .. note:: 217 * 218 * This function should be used for the &struct v4l2_subdev_core_ops 219 * %unsubscribe_event field. 220 */ 221 int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd, 222 struct v4l2_fh *fh, 223 struct v4l2_event_subscription *sub); 224 /** 225 * v4l2_src_change_event_subscribe - helper function that calls 226 * v4l2_event_subscribe() if the event is %V4L2_EVENT_SOURCE_CHANGE. 227 * 228 * @fh: pointer to struct v4l2_fh 229 * @sub: pointer to &struct v4l2_event_subscription 230 */ 231 int v4l2_src_change_event_subscribe(struct v4l2_fh *fh, 232 const struct v4l2_event_subscription *sub); 233 /** 234 * v4l2_src_change_event_subdev_subscribe - Variant of v4l2_event_subscribe(), 235 * meant to subscribe only events of the type %V4L2_EVENT_SOURCE_CHANGE. 236 * 237 * @sd: pointer to &struct v4l2_subdev 238 * @fh: pointer to &struct v4l2_fh 239 * @sub: pointer to &struct v4l2_event_subscription 240 */ 241 int v4l2_src_change_event_subdev_subscribe(struct v4l2_subdev *sd, 242 struct v4l2_fh *fh, 243 struct v4l2_event_subscription *sub); 244 #endif /* V4L2_EVENT_H */ 245