| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
V4L2 events |
| 4 |
----------- |
| 5 |
|
| 6 |
The V4L2 events provide a generic way to pass events to user space. |
| 7 |
The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events. |
| 8 |
|
| 9 |
Events are subscribed per-filehandle. An event specification consists of a |
| 10 |
``type`` and is optionally associated with an object identified through the |
| 11 |
``id`` field. If unused, then the ``id`` is 0. So an event is uniquely |
| 12 |
identified by the ``(type, id)`` tuple. |
| 13 |
|
| 14 |
The :c:type:`v4l2_fh` struct has a list of subscribed events on its |
| 15 |
``subscribed`` field. |
| 16 |
|
| 17 |
When the user subscribes to an event, a :c:type:`v4l2_subscribed_event` |
| 18 |
struct is added to :c:type:`v4l2_fh`\ ``.subscribed``, one for every |
| 19 |
subscribed event. |
| 20 |
|
| 21 |
Each :c:type:`v4l2_subscribed_event` struct ends with a |
| 22 |
:c:type:`v4l2_kevent` ringbuffer, with the size given by the caller |
| 23 |
of :c:func:`v4l2_event_subscribe`. This ringbuffer is used to store any events |
| 24 |
raised by the driver. |
| 25 |
|
| 26 |
So every ``(type, ID)`` event tuple will have its own |
| 27 |
:c:type:`v4l2_kevent` ringbuffer. This guarantees that if a driver is |
| 28 |
generating lots of events of one type in a short time, then that will |
| 29 |
not overwrite events of another type. |
| 30 |
|
| 31 |
But if you get more events of one type than the size of the |
| 32 |
:c:type:`v4l2_kevent` ringbuffer, then the oldest event will be dropped |
| 33 |
and the new one added. |
| 34 |
|
| 35 |
The :c:type:`v4l2_kevent` struct links into the ``available`` |
| 36 |
list of the :c:type:`v4l2_fh` struct so :ref:`VIDIOC_DQEVENT` will |
| 37 |
know which event to dequeue first. |
| 38 |
|
| 39 |
Finally, if the event subscription is associated with a particular object |
| 40 |
such as a V4L2 control, then that object needs to know about that as well |
| 41 |
so that an event can be raised by that object. So the ``node`` field can |
| 42 |
be used to link the :c:type:`v4l2_subscribed_event` struct into a list of |
| 43 |
such objects. |
| 44 |
|
| 45 |
So to summarize: |
| 46 |
|
| 47 |
- struct v4l2_fh has two lists: one of the ``subscribed`` events, |
| 48 |
and one of the ``available`` events. |
| 49 |
|
| 50 |
- struct v4l2_subscribed_event has a ringbuffer of raised |
| 51 |
(pending) events of that particular type. |
| 52 |
|
| 53 |
- If struct v4l2_subscribed_event is associated with a specific |
| 54 |
object, then that object will have an internal list of |
| 55 |
struct v4l2_subscribed_event so it knows who subscribed an |
| 56 |
event to that object. |
| 57 |
|
| 58 |
Furthermore, the internal struct v4l2_subscribed_event has |
| 59 |
``merge()`` and ``replace()`` callbacks which drivers can set. These |
| 60 |
callbacks are called when a new event is raised and there is no more room. |
| 61 |
|
| 62 |
The ``replace()`` callback allows you to replace the payload of the old event |
| 63 |
with that of the new event, merging any relevant data from the old payload |
| 64 |
into the new payload that replaces it. It is called when this event type has |
| 65 |
a ringbuffer with size is one, i.e. only one event can be stored in the |
| 66 |
ringbuffer. |
| 67 |
|
| 68 |
The ``merge()`` callback allows you to merge the oldest event payload into |
| 69 |
that of the second-oldest event payload. It is called when |
| 70 |
the ringbuffer has size is greater than one. |
| 71 |
|
| 72 |
This way no status information is lost, just the intermediate steps leading |
| 73 |
up to that state. |
| 74 |
|
| 75 |
A good example of these ``replace``/``merge`` callbacks is in v4l2-event.c: |
| 76 |
``ctrls_replace()`` and ``ctrls_merge()`` callbacks for the control event. |
| 77 |
|
| 78 |
.. note:: |
| 79 |
these callbacks can be called from interrupt context, so they must |
| 80 |
be fast. |
| 81 |
|
| 82 |
In order to queue events to video device, drivers should call: |
| 83 |
|
| 84 |
:c:func:`v4l2_event_queue <v4l2_event_queue>` |
| 85 |
(:c:type:`vdev <video_device>`, :c:type:`ev <v4l2_event>`) |
| 86 |
|
| 87 |
The driver's only responsibility is to fill in the type and the data fields. |
| 88 |
The other fields will be filled in by V4L2. |
| 89 |
|
| 90 |
Event subscription |
| 91 |
~~~~~~~~~~~~~~~~~~ |
| 92 |
|
| 93 |
Subscribing to an event is via: |
| 94 |
|
| 95 |
:c:func:`v4l2_event_subscribe <v4l2_event_subscribe>` |
| 96 |
(:c:type:`fh <v4l2_fh>`, :c:type:`sub <v4l2_event_subscription>` , |
| 97 |
elems, :c:type:`ops <v4l2_subscribed_event_ops>`) |
| 98 |
|
| 99 |
|
| 100 |
This function is used to implement :c:type:`video_device`-> |
| 101 |
:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_subscribe_event``, |
| 102 |
but the driver must check first if the driver is able to produce events |
| 103 |
with specified event id, and then should call |
| 104 |
:c:func:`v4l2_event_subscribe` to subscribe the event. |
| 105 |
|
| 106 |
The elems argument is the size of the event queue for this event. If it is 0, |
| 107 |
then the framework will fill in a default value (this depends on the event |
| 108 |
type). |
| 109 |
|
| 110 |
The ops argument allows the driver to specify a number of callbacks: |
| 111 |
|
| 112 |
.. tabularcolumns:: |p{1.5cm}|p{16.0cm}| |
| 113 |
|
| 114 |
======== ============================================================== |
| 115 |
Callback Description |
| 116 |
======== ============================================================== |
| 117 |
add called when a new listener gets added (subscribing to the same |
| 118 |
event twice will only cause this callback to get called once) |
| 119 |
del called when a listener stops listening |
| 120 |
replace replace event 'old' with event 'new'. |
| 121 |
merge merge event 'old' into event 'new'. |
| 122 |
======== ============================================================== |
| 123 |
|
| 124 |
All 4 callbacks are optional, if you don't want to specify any callbacks |
| 125 |
the ops argument itself maybe ``NULL``. |
| 126 |
|
| 127 |
Unsubscribing an event |
| 128 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 129 |
|
| 130 |
Unsubscribing to an event is via: |
| 131 |
|
| 132 |
:c:func:`v4l2_event_unsubscribe <v4l2_event_unsubscribe>` |
| 133 |
(:c:type:`fh <v4l2_fh>`, :c:type:`sub <v4l2_event_subscription>`) |
| 134 |
|
| 135 |
This function is used to implement :c:type:`video_device`-> |
| 136 |
:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``. |
| 137 |
A driver may call :c:func:`v4l2_event_unsubscribe` directly unless it |
| 138 |
wants to be involved in unsubscription process. |
| 139 |
|
| 140 |
The special type ``V4L2_EVENT_ALL`` may be used to unsubscribe all events. The |
| 141 |
drivers may want to handle this in a special way. |
| 142 |
|
| 143 |
Check if there's a pending event |
| 144 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 145 |
|
| 146 |
Checking if there's a pending event is via: |
| 147 |
|
| 148 |
:c:func:`v4l2_event_pending <v4l2_event_pending>` |
| 149 |
(:c:type:`fh <v4l2_fh>`) |
| 150 |
|
| 151 |
|
| 152 |
This function returns the number of pending events. Useful when implementing |
| 153 |
poll. |
| 154 |
|
| 155 |
How events work |
| 156 |
~~~~~~~~~~~~~~~ |
| 157 |
|
| 158 |
Events are delivered to user space through the poll system call. The driver |
| 159 |
can use :c:type:`v4l2_fh`->wait (a wait_queue_head_t) as the argument for |
| 160 |
``poll_wait()``. |
| 161 |
|
| 162 |
There are standard and private events. New standard events must use the |
| 163 |
smallest available event type. The drivers must allocate their events from |
| 164 |
their own class starting from class base. Class base is |
| 165 |
``V4L2_EVENT_PRIVATE_START`` + n * 1000 where n is the lowest available number. |
| 166 |
The first event type in the class is reserved for future use, so the first |
| 167 |
available event type is 'class base + 1'. |
| 168 |
|
| 169 |
An example on how the V4L2 events may be used can be found in the OMAP |
| 170 |
3 ISP driver (``drivers/media/platform/ti/omap3isp``). |
| 171 |
|
| 172 |
A subdev can directly send an event to the :c:type:`v4l2_device` notify |
| 173 |
function with ``V4L2_DEVICE_NOTIFY_EVENT``. This allows the bridge to map |
| 174 |
the subdev that sends the event to the video node(s) associated with the |
| 175 |
subdev that need to be informed about such an event. |
| 176 |
|
| 177 |
V4L2 event functions and data structures |
| 178 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 179 |
|
| 180 |
.. kernel-doc:: include/media/v4l2-event.h |
| 181 |
|