path: root/Documentation/video4linux
diff options
authorSakari Ailus <sakari.ailus@maxwell.research.nokia.com>2010-03-27 10:58:24 -0300
committerMauro Carvalho Chehab <mchehab@redhat.com>2010-05-19 12:58:07 -0300
commitdd96608369be9d3cfc604eaa3a53a2d38f1cb415 (patch)
treefc3e9f5f70aef35255fd2cca2e5a88498827d093 /Documentation/video4linux
parentd3d7c963562adad92e968df23c425ae964fe9ce2 (diff)
V4L/DVB: V4L: Events: Add documentation
Add documentation on how to use V4L2 events, both for V4L2 drivers and for V4L2 applications. Signed-off-by: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/video4linux')
1 files changed, 60 insertions, 0 deletions
diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
index 48f0adfbc98..e831aaca66f 100644
--- a/Documentation/video4linux/v4l2-framework.txt
+++ b/Documentation/video4linux/v4l2-framework.txt
@@ -680,3 +680,63 @@ int my_release(struct file *file)
+V4L2 events
+The V4L2 events provide a generic way to pass events to user space.
+The driver must use v4l2_fh to be able to support V4L2 events.
+Useful functions:
+- v4l2_event_alloc()
+ To use events, the driver must allocate events for the file handle. By
+ calling the function more than once, the driver may assure that at least n
+ events in total have been allocated. The function may not be called in
+ atomic context.
+- v4l2_event_queue()
+ Queue events to video device. The driver's only responsibility is to fill
+ in the type and the data fields. The other fields will be filled in by
+ V4L2.
+- v4l2_event_subscribe()
+ The video_device->ioctl_ops->vidioc_subscribe_event must check the driver
+ is able to produce events with specified event id. Then it calls
+ v4l2_event_subscribe() to subscribe the event.
+- v4l2_event_unsubscribe()
+ vidioc_unsubscribe_event in struct v4l2_ioctl_ops. A driver may use
+ v4l2_event_unsubscribe() directly unless it wants to be involved in
+ unsubscription process.
+ The special type V4L2_EVENT_ALL may be used to unsubscribe all events. The
+ drivers may want to handle this in a special way.
+- v4l2_event_pending()
+ Returns the number of pending events. Useful when implementing poll.
+Drivers do not initialise events directly. The events are initialised
+through v4l2_fh_init() if video_device->ioctl_ops->vidioc_subscribe_event is
+non-NULL. This *MUST* be performed in the driver's
+v4l2_file_operations->open() handler.
+Events are delivered to user space through the poll system call. The driver
+can use v4l2_fh->events->wait wait_queue_head_t as the argument for
+There are standard and private events. New standard events must use the
+smallest available event type. The drivers must allocate their events from
+their own class starting from class base. Class base is
+V4L2_EVENT_PRIVATE_START + n * 1000 where n is the lowest available number.
+The first event type in the class is reserved for future use, so the first
+available event type is 'class base + 1'.
+An example on how the V4L2 events may be used can be found in the OMAP
+3 ISP driver available at <URL:http://gitorious.org/omap3camera> as of
+writing this.