Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 3ad57c33 authored by Hans Verkuil's avatar Hans Verkuil Committed by Mauro Carvalho Chehab
Browse files

[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: default avatarHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 3f66f0ed
Loading
Loading
Loading
Loading
+34 −0
Original line number Diff line number Diff line
@@ -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;