1*059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 254f38fcaSMauro Carvalho Chehab 354f38fcaSMauro Carvalho Chehab.. _event: 454f38fcaSMauro Carvalho Chehab 554f38fcaSMauro Carvalho Chehab*************** 654f38fcaSMauro Carvalho ChehabEvent Interface 754f38fcaSMauro Carvalho Chehab*************** 854f38fcaSMauro Carvalho Chehab 954f38fcaSMauro Carvalho ChehabThe V4L2 event interface provides a means for a user to get immediately 1054f38fcaSMauro Carvalho Chehabnotified on certain conditions taking place on a device. This might 1154f38fcaSMauro Carvalho Chehabinclude start of frame or loss of signal events, for example. Changes in 1254f38fcaSMauro Carvalho Chehabthe value or state of a V4L2 control can also be reported through 1354f38fcaSMauro Carvalho Chehabevents. 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabTo receive events, the events the user is interested in first must be 1654f38fcaSMauro Carvalho Chehabsubscribed using the 1754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once 1854f38fcaSMauro Carvalho Chehaban event is subscribed, the events of subscribed types are dequeueable 1954f38fcaSMauro Carvalho Chehabusing the :ref:`VIDIOC_DQEVENT` ioctl. Events may be 2054f38fcaSMauro Carvalho Chehabunsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event 2154f38fcaSMauro Carvalho Chehabtype V4L2_EVENT_ALL may be used to unsubscribe all the events the 2254f38fcaSMauro Carvalho Chehabdriver supports. 2354f38fcaSMauro Carvalho Chehab 2454f38fcaSMauro Carvalho ChehabThe event subscriptions and event queues are specific to file handles. 2554f38fcaSMauro Carvalho ChehabSubscribing an event on one file handle does not affect other file 2654f38fcaSMauro Carvalho Chehabhandles. 2754f38fcaSMauro Carvalho Chehab 2854f38fcaSMauro Carvalho ChehabThe information on dequeueable events is obtained by using select or 2954f38fcaSMauro Carvalho Chehabpoll system calls on video devices. The V4L2 events use POLLPRI events 3054f38fcaSMauro Carvalho Chehabon poll system call and exceptions on select system call. 3154f38fcaSMauro Carvalho Chehab 3254f38fcaSMauro Carvalho ChehabStarting with kernel 3.1 certain guarantees can be given with regards to 3354f38fcaSMauro Carvalho Chehabevents: 3454f38fcaSMauro Carvalho Chehab 3554f38fcaSMauro Carvalho Chehab1. Each subscribed event has its own internal dedicated event queue. 3654f38fcaSMauro Carvalho Chehab This means that flooding of one event type will not interfere with 3754f38fcaSMauro Carvalho Chehab other event types. 3854f38fcaSMauro Carvalho Chehab 3954f38fcaSMauro Carvalho Chehab2. If the internal event queue for a particular subscribed event becomes 4054f38fcaSMauro Carvalho Chehab full, then the oldest event in that queue will be dropped. 4154f38fcaSMauro Carvalho Chehab 4254f38fcaSMauro Carvalho Chehab3. Where applicable, certain event types can ensure that the payload of 4354f38fcaSMauro Carvalho Chehab the oldest event that is about to be dropped will be merged with the 4454f38fcaSMauro Carvalho Chehab payload of the next oldest event. Thus ensuring that no information 4554f38fcaSMauro Carvalho Chehab is lost, but only an intermediate step leading up to that 4654f38fcaSMauro Carvalho Chehab information. See the documentation for the event you want to 4754f38fcaSMauro Carvalho Chehab subscribe to whether this is applicable for that event or not. 48