diff options
author | Sakari Ailus <sakari.ailus@maxwell.research.nokia.com> | 2010-03-27 10:58:24 -0300 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@redhat.com> | 2010-05-19 12:58:07 -0300 |
commit | dd96608369be9d3cfc604eaa3a53a2d38f1cb415 (patch) | |
tree | fc3e9f5f70aef35255fd2cca2e5a88498827d093 /Documentation/video4linux | |
parent | d3d7c963562adad92e968df23c425ae964fe9ce2 (diff) | |
download | kernel_samsung_tuna-dd96608369be9d3cfc604eaa3a53a2d38f1cb415.zip kernel_samsung_tuna-dd96608369be9d3cfc604eaa3a53a2d38f1cb415.tar.gz kernel_samsung_tuna-dd96608369be9d3cfc604eaa3a53a2d38f1cb415.tar.bz2 |
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')
-rw-r--r-- | Documentation/video4linux/v4l2-framework.txt | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index 48f0adf..e831aac 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 +poll_wait(). + +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. |