| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _event: |
| 5 |
|
| 6 |
*************** |
| 7 |
Event Interface |
| 8 |
*************** |
| 9 |
|
| 10 |
The V4L2 event interface provides a means for a user to get immediately |
| 11 |
notified on certain conditions taking place on a device. This might |
| 12 |
include start of frame or loss of signal events, for example. Changes in |
| 13 |
the value or state of a V4L2 control can also be reported through |
| 14 |
events. |
| 15 |
|
| 16 |
To receive events, the events the user is interested in first must be |
| 17 |
subscribed using the |
| 18 |
:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once |
| 19 |
an event is subscribed, the events of subscribed types are dequeueable |
| 20 |
using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be |
| 21 |
unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event |
| 22 |
type V4L2_EVENT_ALL may be used to unsubscribe all the events the |
| 23 |
driver supports. |
| 24 |
|
| 25 |
The event subscriptions and event queues are specific to file handles. |
| 26 |
Subscribing an event on one file handle does not affect other file |
| 27 |
handles. |
| 28 |
|
| 29 |
The information on dequeueable events is obtained by using select or |
| 30 |
poll system calls on video devices. The V4L2 events use POLLPRI events |
| 31 |
on poll system call and exceptions on select system call. |
| 32 |
|
| 33 |
Starting with kernel 3.1 certain guarantees can be given with regards to |
| 34 |
events: |
| 35 |
|
| 36 |
1. 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 |
|
| 40 |
2. If the internal event queue for a particular subscribed event becomes |
| 41 |
full, then the oldest event in that queue will be dropped. |
| 42 |
|
| 43 |
3. 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. |