1 .. SPDX-License-Identifier: GPL-2.0
2
3 V4L2 events
4 -----------
5
6 The V4L2 events provide a generic way to pass
7 The driver must use :c:type:`v4l2_fh` to be ab
8
9 Events are subscribed per-filehandle. An event
10 ``type`` and is optionally associated with an
11 ``id`` field. If unused, then the ``id`` is 0.
12 identified by the ``(type, id)`` tuple.
13
14 The :c:type:`v4l2_fh` struct has a list of sub
15 ``subscribed`` field.
16
17 When the user subscribes to an event, a :c:typ
18 struct is added to :c:type:`v4l2_fh`\ ``.subsc
19 subscribed event.
20
21 Each :c:type:`v4l2_subscribed_event` struct en
22 :c:type:`v4l2_kevent` ringbuffer, with the siz
23 of :c:func:`v4l2_event_subscribe`. This ringbu
24 raised by the driver.
25
26 So every ``(type, ID)`` event tuple will have
27 :c:type:`v4l2_kevent` ringbuffer. This guarant
28 generating lots of events of one type in a sho
29 not overwrite events of another type.
30
31 But if you get more events of one type than th
32 :c:type:`v4l2_kevent` ringbuffer, then the old
33 and the new one added.
34
35 The :c:type:`v4l2_kevent` struct links into th
36 list of the :c:type:`v4l2_fh` struct so :ref:`
37 know which event to dequeue first.
38
39 Finally, if the event subscription is associat
40 such as a V4L2 control, then that object needs
41 so that an event can be raised by that object.
42 be used to link the :c:type:`v4l2_subscribed_e
43 such objects.
44
45 So to summarize:
46
47 - struct v4l2_fh has two lists: one of the ``s
48 and one of the ``available`` events.
49
50 - struct v4l2_subscribed_event has a ringbuffe
51 (pending) events of that particular type.
52
53 - If struct v4l2_subscribed_event is associate
54 object, then that object will have an intern
55 struct v4l2_subscribed_event so it knows who
56 event to that object.
57
58 Furthermore, the internal struct v4l2_subscrib
59 ``merge()`` and ``replace()`` callbacks which
60 callbacks are called when a new event is raise
61
62 The ``replace()`` callback allows you to repla
63 with that of the new event, merging any releva
64 into the new payload that replaces it. It is c
65 a ringbuffer with size is one, i.e. only one e
66 ringbuffer.
67
68 The ``merge()`` callback allows you to merge t
69 that of the second-oldest event payload. It is
70 the ringbuffer has size is greater than one.
71
72 This way no status information is lost, just t
73 up to that state.
74
75 A good example of these ``replace``/``merge``
76 ``ctrls_replace()`` and ``ctrls_merge()`` call
77
78 .. note::
79 these callbacks can be called from int
80 be fast.
81
82 In order to queue events to video device, driv
83
84 :c:func:`v4l2_event_queue <v4l2_event_
85 (:c:type:`vdev <video_device>`, :c:typ
86
87 The driver's only responsibility is to fill in
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_ev
96 (:c:type:`fh <v4l2_fh>`, :c:type:`sub
97 elems, :c:type:`ops <v4l2_subscribed_e
98
99
100 This function is used to implement :c:type:`vi
101 :c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidio
102 but the driver must check first if the driver
103 with specified event id, and then should call
104 :c:func:`v4l2_event_subscribe` to subscribe th
105
106 The elems argument is the size of the event qu
107 then the framework will fill in a default valu
108 type).
109
110 The ops argument allows the driver to specify
111
112 .. tabularcolumns:: |p{1.5cm}|p{16.0cm}|
113
114 ======== =====================================
115 Callback Description
116 ======== =====================================
117 add called when a new listener gets added
118 event twice will only cause this call
119 del called when a listener stops listenin
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 wan
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_
133 (:c:type:`fh <v4l2_fh>`, :c:type:`sub
134
135 This function is used to implement :c:type:`vi
136 :c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidio
137 A driver may call :c:func:`v4l2_event_unsubscr
138 wants to be involved in unsubscription process
139
140 The special type ``V4L2_EVENT_ALL`` may be use
141 drivers may want to handle this in a special w
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_even
149 (:c:type:`fh <v4l2_fh>`)
150
151
152 This function returns the number of pending ev
153 poll.
154
155 How events work
156 ~~~~~~~~~~~~~~~
157
158 Events are delivered to user space through the
159 can use :c:type:`v4l2_fh`->wait (a wait_queue_
160 ``poll_wait()``.
161
162 There are standard and private events. New sta
163 smallest available event type. The drivers mus
164 their own class starting from class base. Clas
165 ``V4L2_EVENT_PRIVATE_START`` + n * 1000 where
166 The first event type in the class is reserved
167 available event type is 'class base + 1'.
168
169 An example on how the V4L2 events may be used
170 3 ISP driver (``drivers/media/platform/ti/omap
171
172 A subdev can directly send an event to the :c:
173 function with ``V4L2_DEVICE_NOTIFY_EVENT``. Th
174 the subdev that sends the event to the video n
175 subdev that need to be informed about such an
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.