162306a36Sopenharmony_ci.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 262306a36Sopenharmony_ci 362306a36Sopenharmony_ci.. _event: 462306a36Sopenharmony_ci 562306a36Sopenharmony_ci*************** 662306a36Sopenharmony_ciEvent Interface 762306a36Sopenharmony_ci*************** 862306a36Sopenharmony_ci 962306a36Sopenharmony_ciThe V4L2 event interface provides a means for a user to get immediately 1062306a36Sopenharmony_cinotified on certain conditions taking place on a device. This might 1162306a36Sopenharmony_ciinclude start of frame or loss of signal events, for example. Changes in 1262306a36Sopenharmony_cithe value or state of a V4L2 control can also be reported through 1362306a36Sopenharmony_cievents. 1462306a36Sopenharmony_ci 1562306a36Sopenharmony_ciTo receive events, the events the user is interested in first must be 1662306a36Sopenharmony_cisubscribed using the 1762306a36Sopenharmony_ci:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once 1862306a36Sopenharmony_cian event is subscribed, the events of subscribed types are dequeueable 1962306a36Sopenharmony_ciusing the :ref:`VIDIOC_DQEVENT` ioctl. Events may be 2062306a36Sopenharmony_ciunsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event 2162306a36Sopenharmony_citype V4L2_EVENT_ALL may be used to unsubscribe all the events the 2262306a36Sopenharmony_cidriver supports. 2362306a36Sopenharmony_ci 2462306a36Sopenharmony_ciThe event subscriptions and event queues are specific to file handles. 2562306a36Sopenharmony_ciSubscribing an event on one file handle does not affect other file 2662306a36Sopenharmony_cihandles. 2762306a36Sopenharmony_ci 2862306a36Sopenharmony_ciThe information on dequeueable events is obtained by using select or 2962306a36Sopenharmony_cipoll system calls on video devices. The V4L2 events use POLLPRI events 3062306a36Sopenharmony_cion poll system call and exceptions on select system call. 3162306a36Sopenharmony_ci 3262306a36Sopenharmony_ciStarting with kernel 3.1 certain guarantees can be given with regards to 3362306a36Sopenharmony_cievents: 3462306a36Sopenharmony_ci 3562306a36Sopenharmony_ci1. Each subscribed event has its own internal dedicated event queue. 3662306a36Sopenharmony_ci This means that flooding of one event type will not interfere with 3762306a36Sopenharmony_ci other event types. 3862306a36Sopenharmony_ci 3962306a36Sopenharmony_ci2. If the internal event queue for a particular subscribed event becomes 4062306a36Sopenharmony_ci full, then the oldest event in that queue will be dropped. 4162306a36Sopenharmony_ci 4262306a36Sopenharmony_ci3. Where applicable, certain event types can ensure that the payload of 4362306a36Sopenharmony_ci the oldest event that is about to be dropped will be merged with the 4462306a36Sopenharmony_ci payload of the next oldest event. Thus ensuring that no information 4562306a36Sopenharmony_ci is lost, but only an intermediate step leading up to that 4662306a36Sopenharmony_ci information. See the documentation for the event you want to 4762306a36Sopenharmony_ci subscribe to whether this is applicable for that event or not. 48