|author||Hans Verkuil <email@example.com>||2011-06-20 12:00:36 -0300|
|committer||Mauro Carvalho Chehab <firstname.lastname@example.org>||2011-07-27 17:53:34 -0300|
[media] v4l2-event.h: add overview documentation to the header
It's getting confusing who is linking to what, so add an overview at the start of the header. Signed-off-by: Hans Verkuil <email@example.com> Signed-off-by: Mauro Carvalho Chehab <firstname.lastname@example.org>
Diffstat (limited to 'include/media/v4l2-event.h')
1 files changed, 34 insertions, 0 deletions
diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h
index 7abeb397d13..5f14e8895ce 100644
@@ -29,6 +29,40 @@
+ * Overview:
+ * Events are subscribed per-filehandle. An event specification consists of a
+ * type and is optionally associated with an object identified through the
+ * 'id' field. So an event is uniquely identified by the (type, id) tuple.
+ * The v4l2-fh struct has a list of subscribed events. The v4l2_subscribed_event
+ * struct is added to that list, one for every subscribed event.
+ * Each v4l2_subscribed_event struct ends with an array of v4l2_kevent structs.
+ * This array (ringbuffer, really) is used to store any events raised by the
+ * driver. The v4l2_kevent struct links into the 'available' list of the
+ * v4l2_fh struct so VIDIOC_DQEVENT will know which event to dequeue first.
+ * Finally, if the event subscription is associated with a particular object
+ * such as a V4L2 control, then that object needs to know about that as well
+ * so that an event can be raised by that object. So the 'node' field can
+ * be used to link the v4l2_subscribed_event struct into a list of that
+ * object.
+ * So to summarize:
+ * struct v4l2_fh has two lists: one of the subscribed events, and one of the
+ * pending events.
+ * struct v4l2_subscribed_event has a ringbuffer of raised (pending) events of
+ * that particular type.
+ * If struct v4l2_subscribed_event is associated with a specific object, then
+ * that object will have an internal list of struct v4l2_subscribed_event so
+ * it knows who subscribed an event to that object.