1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _event:
11
12***************
13Event Interface
14***************
15
16The V4L2 event interface provides a means for a user to get immediately
17notified on certain conditions taking place on a device. This might
18include start of frame or loss of signal events, for example. Changes in
19the value or state of a V4L2 control can also be reported through
20events.
21
22To receive events, the events the user is interested in first must be
23subscribed using the
24:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once
25an event is subscribed, the events of subscribed types are dequeueable
26using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be
27unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
28type V4L2_EVENT_ALL may be used to unsubscribe all the events the
29driver supports.
30
31The event subscriptions and event queues are specific to file handles.
32Subscribing an event on one file handle does not affect other file
33handles.
34
35The information on dequeueable events is obtained by using select or
36poll system calls on video devices. The V4L2 events use POLLPRI events
37on poll system call and exceptions on select system call.
38
39Starting with kernel 3.1 certain guarantees can be given with regards to
40events:
41
421. Each subscribed event has its own internal dedicated event queue.
43   This means that flooding of one event type will not interfere with
44   other event types.
45
462. If the internal event queue for a particular subscribed event becomes
47   full, then the oldest event in that queue will be dropped.
48
493. Where applicable, certain event types can ensure that the payload of
50   the oldest event that is about to be dropped will be merged with the
51   payload of the next oldest event. Thus ensuring that no information
52   is lost, but only an intermediate step leading up to that
53   information. See the documentation for the event you want to
54   subscribe to whether this is applicable for that event or not.
55