summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorHans Verkuil <hans.verkuil@cisco.com>2011-06-20 12:00:36 -0300
committerMauro Carvalho Chehab <mchehab@redhat.com>2011-07-27 17:53:34 -0300
commit3ad57c33846d884cfeed770238b27f3dcf3742f1 (patch)
tree64736a199f7b727fa408a5fa769774986e8b8727
parent3f66f0ed319505555f45ceac04775b23f9279ee6 (diff)
downloadlinux-3ad57c33846d884cfeed770238b27f3dcf3742f1.tar.bz2
[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 <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
-rw-r--r--include/media/v4l2-event.h34
1 files changed, 34 insertions, 0 deletions
diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h
index 7abeb397d130..5f14e8895ce2 100644
--- a/include/media/v4l2-event.h
+++ b/include/media/v4l2-event.h
@@ -29,6 +29,40 @@
#include <linux/videodev2.h>
#include <linux/wait.h>
+/*
+ * 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.
+ */
+
struct v4l2_fh;
struct v4l2_subscribed_event;
struct video_device;