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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.