1 /* 2 * v4l2-event.h 3 * 4 * V4L2 events. 5 * 6 * Copyright (C) 2009--2010 Nokia Corporation. 7 * 8 * Contact: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com> 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_subscribed_event; 68 struct video_device; 69 70 /** struct v4l2_kevent - Internal kernel event struct. 71 * @list: List node for the v4l2_fh->available list. 72 * @sev: Pointer to parent v4l2_subscribed_event. 73 * @event: The event itself. 74 */ 75 struct v4l2_kevent { 76 struct list_head list; 77 struct v4l2_subscribed_event *sev; 78 struct v4l2_event event; 79 }; 80 81 /** struct v4l2_subscribed_event - Internal struct representing a subscribed event. 82 * @list: List node for the v4l2_fh->subscribed list. 83 * @type: Event type. 84 * @id: Associated object ID (e.g. control ID). 0 if there isn't any. 85 * @flags: Copy of v4l2_event_subscription->flags. 86 * @fh: Filehandle that subscribed to this event. 87 * @node: List node that hooks into the object's event list (if there is one). 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 * @elems: The number of elements in the events array. 91 * @first: The index of the events containing the oldest available event. 92 * @in_use: The number of queued events. 93 * @events: An array of @elems events. 94 */ 95 struct v4l2_subscribed_event { 96 struct list_head list; 97 u32 type; 98 u32 id; 99 u32 flags; 100 struct v4l2_fh *fh; 101 struct list_head node; 102 void (*replace)(struct v4l2_event *old, 103 const struct v4l2_event *new); 104 void (*merge)(const struct v4l2_event *old, 105 struct v4l2_event *new); 106 unsigned elems; 107 unsigned first; 108 unsigned in_use; 109 struct v4l2_kevent events[]; 110 }; 111 112 int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event, 113 int nonblocking); 114 void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev); 115 void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev); 116 int v4l2_event_pending(struct v4l2_fh *fh); 117 int v4l2_event_subscribe(struct v4l2_fh *fh, 118 struct v4l2_event_subscription *sub, unsigned elems); 119 int v4l2_event_unsubscribe(struct v4l2_fh *fh, 120 struct v4l2_event_subscription *sub); 121 void v4l2_event_unsubscribe_all(struct v4l2_fh *fh); 122 123 #endif /* V4L2_EVENT_H */ 124