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