1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 2
3 .. _event: 3 .. _event:
4 4
5 *************** 5 ***************
6 Event Interface 6 Event Interface
7 *************** 7 ***************
8 8
9 The V4L2 event interface provides a means for 9 The V4L2 event interface provides a means for a user to get immediately
10 notified on certain conditions taking place on 10 notified on certain conditions taking place on a device. This might
11 include start of frame or loss of signal event 11 include start of frame or loss of signal events, for example. Changes in
12 the value or state of a V4L2 control can also 12 the value or state of a V4L2 control can also be reported through
13 events. 13 events.
14 14
15 To receive events, the events the user is inte 15 To receive events, the events the user is interested in first must be
16 subscribed using the 16 subscribed using the
17 :ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once 17 :ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once
18 an event is subscribed, the events of subscrib 18 an event is subscribed, the events of subscribed types are dequeueable
19 using the :ref:`VIDIOC_DQEVENT` ioctl. Events 19 using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be
20 unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT io 20 unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
21 type V4L2_EVENT_ALL may be used to unsubscribe 21 type V4L2_EVENT_ALL may be used to unsubscribe all the events the
22 driver supports. 22 driver supports.
23 23
24 The event subscriptions and event queues are s 24 The event subscriptions and event queues are specific to file handles.
25 Subscribing an event on one file handle does n 25 Subscribing an event on one file handle does not affect other file
26 handles. 26 handles.
27 27
28 The information on dequeueable events is obtai 28 The information on dequeueable events is obtained by using select or
29 poll system calls on video devices. The V4L2 e 29 poll system calls on video devices. The V4L2 events use POLLPRI events
30 on poll system call and exceptions on select s 30 on poll system call and exceptions on select system call.
31 31
32 Starting with kernel 3.1 certain guarantees ca 32 Starting with kernel 3.1 certain guarantees can be given with regards to
33 events: 33 events:
34 34
35 1. Each subscribed event has its own internal 35 1. Each subscribed event has its own internal dedicated event queue.
36 This means that flooding of one event type 36 This means that flooding of one event type will not interfere with
37 other event types. 37 other event types.
38 38
39 2. If the internal event queue for a particula 39 2. If the internal event queue for a particular subscribed event becomes
40 full, then the oldest event in that queue w 40 full, then the oldest event in that queue will be dropped.
41 41
42 3. Where applicable, certain event types can e 42 3. Where applicable, certain event types can ensure that the payload of
43 the oldest event that is about to be droppe 43 the oldest event that is about to be dropped will be merged with the
44 payload of the next oldest event. Thus ensu 44 payload of the next oldest event. Thus ensuring that no information
45 is lost, but only an intermediate step lead 45 is lost, but only an intermediate step leading up to that
46 information. See the documentation for the 46 information. See the documentation for the event you want to
47 subscribe to whether this is applicable for 47 subscribe to whether this is applicable for that event or not.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.