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 /** struct v4l2_kevent - Internal kernel event struct. 72 * @list: List node for the v4l2_fh->available list. 73 * @sev: Pointer to parent v4l2_subscribed_event. 74 * @event: The event itself. 75 */ 76 struct v4l2_kevent { 77 struct list_head list; 78 struct v4l2_subscribed_event *sev; 79 struct v4l2_event event; 80 }; 81 82 /** struct v4l2_subscribed_event_ops - Subscribed event operations. 83 * @add: Optional callback, called when a new listener is added 84 * @del: Optional callback, called when a listener stops listening 85 * @replace: Optional callback that can replace event 'old' with event 'new'. 86 * @merge: Optional callback that can merge event 'old' into event 'new'. 87 */ 88 struct v4l2_subscribed_event_ops { 89 int (*add)(struct v4l2_subscribed_event *sev, unsigned elems); 90 void (*del)(struct v4l2_subscribed_event *sev); 91 void (*replace)(struct v4l2_event *old, const struct v4l2_event *new); 92 void (*merge)(const struct v4l2_event *old, struct v4l2_event *new); 93 }; 94 95 /** struct v4l2_subscribed_event - Internal struct representing a subscribed event. 96 * @list: List node for the v4l2_fh->subscribed list. 97 * @type: Event type. 98 * @id: Associated object ID (e.g. control ID). 0 if there isn't any. 99 * @flags: Copy of v4l2_event_subscription->flags. 100 * @fh: Filehandle that subscribed to this event. 101 * @node: List node that hooks into the object's event list (if there is one). 102 * @ops: v4l2_subscribed_event_ops 103 * @elems: The number of elements in the events array. 104 * @first: The index of the events containing the oldest available event. 105 * @in_use: The number of queued events. 106 * @events: An array of @elems events. 107 */ 108 struct v4l2_subscribed_event { 109 struct list_head list; 110 u32 type; 111 u32 id; 112 u32 flags; 113 struct v4l2_fh *fh; 114 struct list_head node; 115 const struct v4l2_subscribed_event_ops *ops; 116 unsigned elems; 117 unsigned first; 118 unsigned in_use; 119 struct v4l2_kevent events[]; 120 }; 121 122 int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event, 123 int nonblocking); 124 void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev); 125 void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev); 126 int v4l2_event_pending(struct v4l2_fh *fh); 127 int v4l2_event_subscribe(struct v4l2_fh *fh, 128 const struct v4l2_event_subscription *sub, unsigned elems, 129 const struct v4l2_subscribed_event_ops *ops); 130 int v4l2_event_unsubscribe(struct v4l2_fh *fh, 131 const struct v4l2_event_subscription *sub); 132 void v4l2_event_unsubscribe_all(struct v4l2_fh *fh); 133 int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd, struct v4l2_fh *fh, 134 struct v4l2_event_subscription *sub); 135 #endif /* V4L2_EVENT_H */ 136