18c2ecf20Sopenharmony_ci.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 28c2ecf20Sopenharmony_ci 38c2ecf20Sopenharmony_ci.. _event: 48c2ecf20Sopenharmony_ci 58c2ecf20Sopenharmony_ci*************** 68c2ecf20Sopenharmony_ciEvent Interface 78c2ecf20Sopenharmony_ci*************** 88c2ecf20Sopenharmony_ci 98c2ecf20Sopenharmony_ciThe V4L2 event interface provides a means for a user to get immediately 108c2ecf20Sopenharmony_cinotified on certain conditions taking place on a device. This might 118c2ecf20Sopenharmony_ciinclude start of frame or loss of signal events, for example. Changes in 128c2ecf20Sopenharmony_cithe value or state of a V4L2 control can also be reported through 138c2ecf20Sopenharmony_cievents. 148c2ecf20Sopenharmony_ci 158c2ecf20Sopenharmony_ciTo receive events, the events the user is interested in first must be 168c2ecf20Sopenharmony_cisubscribed using the 178c2ecf20Sopenharmony_ci:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once 188c2ecf20Sopenharmony_cian event is subscribed, the events of subscribed types are dequeueable 198c2ecf20Sopenharmony_ciusing the :ref:`VIDIOC_DQEVENT` ioctl. Events may be 208c2ecf20Sopenharmony_ciunsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event 218c2ecf20Sopenharmony_citype V4L2_EVENT_ALL may be used to unsubscribe all the events the 228c2ecf20Sopenharmony_cidriver supports. 238c2ecf20Sopenharmony_ci 248c2ecf20Sopenharmony_ciThe event subscriptions and event queues are specific to file handles. 258c2ecf20Sopenharmony_ciSubscribing an event on one file handle does not affect other file 268c2ecf20Sopenharmony_cihandles. 278c2ecf20Sopenharmony_ci 288c2ecf20Sopenharmony_ciThe information on dequeueable events is obtained by using select or 298c2ecf20Sopenharmony_cipoll system calls on video devices. The V4L2 events use POLLPRI events 308c2ecf20Sopenharmony_cion poll system call and exceptions on select system call. 318c2ecf20Sopenharmony_ci 328c2ecf20Sopenharmony_ciStarting with kernel 3.1 certain guarantees can be given with regards to 338c2ecf20Sopenharmony_cievents: 348c2ecf20Sopenharmony_ci 358c2ecf20Sopenharmony_ci1. Each subscribed event has its own internal dedicated event queue. 368c2ecf20Sopenharmony_ci This means that flooding of one event type will not interfere with 378c2ecf20Sopenharmony_ci other event types. 388c2ecf20Sopenharmony_ci 398c2ecf20Sopenharmony_ci2. If the internal event queue for a particular subscribed event becomes 408c2ecf20Sopenharmony_ci full, then the oldest event in that queue will be dropped. 418c2ecf20Sopenharmony_ci 428c2ecf20Sopenharmony_ci3. Where applicable, certain event types can ensure that the payload of 438c2ecf20Sopenharmony_ci the oldest event that is about to be dropped will be merged with the 448c2ecf20Sopenharmony_ci payload of the next oldest event. Thus ensuring that no information 458c2ecf20Sopenharmony_ci is lost, but only an intermediate step leading up to that 468c2ecf20Sopenharmony_ci information. See the documentation for the event you want to 478c2ecf20Sopenharmony_ci subscribe to whether this is applicable for that event or not. 48