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