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