0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _event:
0004
0005 ***************
0006 Event Interface
0007 ***************
0008
0009 The V4L2 event interface provides a means for a user to get immediately
0010 notified on certain conditions taking place on a device. This might
0011 include start of frame or loss of signal events, for example. Changes in
0012 the value or state of a V4L2 control can also be reported through
0013 events.
0014
0015 To receive events, the events the user is interested in first must be
0016 subscribed using the
0017 :ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once
0018 an event is subscribed, the events of subscribed types are dequeueable
0019 using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be
0020 unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
0021 type V4L2_EVENT_ALL may be used to unsubscribe all the events the
0022 driver supports.
0023
0024 The event subscriptions and event queues are specific to file handles.
0025 Subscribing an event on one file handle does not affect other file
0026 handles.
0027
0028 The information on dequeueable events is obtained by using select or
0029 poll system calls on video devices. The V4L2 events use POLLPRI events
0030 on poll system call and exceptions on select system call.
0031
0032 Starting with kernel 3.1 certain guarantees can be given with regards to
0033 events:
0034
0035 1. Each subscribed event has its own internal dedicated event queue.
0036 This means that flooding of one event type will not interfere with
0037 other event types.
0038
0039 2. If the internal event queue for a particular subscribed event becomes
0040 full, then the oldest event in that queue will be dropped.
0041
0042 3. Where applicable, certain event types can ensure that the payload of
0043 the oldest event that is about to be dropped will be merged with the
0044 payload of the next oldest event. Thus ensuring that no information
0045 is lost, but only an intermediate step leading up to that
0046 information. See the documentation for the event you want to
0047 subscribe to whether this is applicable for that event or not.
