GNU Linux-libre 4.14.295-gnu1
[releases.git] / Documentation / media / uapi / v4l / vidioc-dqevent.rst
1 .. -*- coding: utf-8; mode: rst -*-
2
3 .. _VIDIOC_DQEVENT:
4
5 ********************
6 ioctl VIDIOC_DQEVENT
7 ********************
8
9 Name
10 ====
11
12 VIDIOC_DQEVENT - Dequeue event
13
14
15 Synopsis
16 ========
17
18 .. c:function:: int ioctl( int fd, VIDIOC_DQEVENT, struct v4l2_event *argp )
19     :name: VIDIOC_DQEVENT
20
21
22 Arguments
23 =========
24
25 ``fd``
26     File descriptor returned by :ref:`open() <func-open>`.
27
28 ``argp``
29     Pointer to struct :c:type:`v4l2_event`.
30
31
32 Description
33 ===========
34
35 Dequeue an event from a video device. No input is required for this
36 ioctl. All the fields of the struct :c:type:`v4l2_event`
37 structure are filled by the driver. The file handle will also receive
38 exceptions which the application may get by e.g. using the select system
39 call.
40
41
42 .. tabularcolumns:: |p{3.0cm}|p{4.4cm}|p{2.4cm}|p{7.7cm}|
43
44 .. c:type:: v4l2_event
45
46 .. cssclass: longtable
47
48 .. flat-table:: struct v4l2_event
49     :header-rows:  0
50     :stub-columns: 0
51     :widths:       1 1 2 1
52
53     * - __u32
54       - ``type``
55       -
56       - Type of the event, see :ref:`event-type`.
57     * - union
58       - ``u``
59       -
60       -
61     * -
62       - struct :c:type:`v4l2_event_vsync`
63       - ``vsync``
64       - Event data for event ``V4L2_EVENT_VSYNC``.
65     * -
66       - struct :c:type:`v4l2_event_ctrl`
67       - ``ctrl``
68       - Event data for event ``V4L2_EVENT_CTRL``.
69     * -
70       - struct :c:type:`v4l2_event_frame_sync`
71       - ``frame_sync``
72       - Event data for event ``V4L2_EVENT_FRAME_SYNC``.
73     * -
74       - struct :c:type:`v4l2_event_motion_det`
75       - ``motion_det``
76       - Event data for event V4L2_EVENT_MOTION_DET.
77     * -
78       - struct :c:type:`v4l2_event_src_change`
79       - ``src_change``
80       - Event data for event V4L2_EVENT_SOURCE_CHANGE.
81     * -
82       - __u8
83       - ``data``\ [64]
84       - Event data. Defined by the event type. The union should be used to
85         define easily accessible type for events.
86     * - __u32
87       - ``pending``
88       -
89       - Number of pending events excluding this one.
90     * - __u32
91       - ``sequence``
92       -
93       - Event sequence number. The sequence number is incremented for
94         every subscribed event that takes place. If sequence numbers are
95         not contiguous it means that events have been lost.
96     * - struct timespec
97       - ``timestamp``
98       -
99       - Event timestamp. The timestamp has been taken from the
100         ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2,
101         use :c:func:`clock_gettime`.
102     * - u32
103       - ``id``
104       -
105       - The ID associated with the event source. If the event does not
106         have an associated ID (this depends on the event type), then this
107         is 0.
108     * - __u32
109       - ``reserved``\ [8]
110       -
111       - Reserved for future extensions. Drivers must set the array to
112         zero.
113
114
115
116 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
117
118 .. cssclass:: longtable
119
120 .. _event-type:
121
122 .. flat-table:: Event Types
123     :header-rows:  0
124     :stub-columns: 0
125     :widths:       3 1 4
126
127     * - ``V4L2_EVENT_ALL``
128       - 0
129       - All events. V4L2_EVENT_ALL is valid only for
130         VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.
131     * - ``V4L2_EVENT_VSYNC``
132       - 1
133       - This event is triggered on the vertical sync. This event has a
134         struct :c:type:`v4l2_event_vsync` associated
135         with it.
136     * - ``V4L2_EVENT_EOS``
137       - 2
138       - This event is triggered when the end of a stream is reached. This
139         is typically used with MPEG decoders to report to the application
140         when the last of the MPEG stream has been decoded.
141     * - ``V4L2_EVENT_CTRL``
142       - 3
143       - This event requires that the ``id`` matches the control ID from
144         which you want to receive events. This event is triggered if the
145         control's value changes, if a button control is pressed or if the
146         control's flags change. This event has a struct
147         :c:type:`v4l2_event_ctrl` associated with it.
148         This struct contains much of the same information as struct
149         :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct
150         :c:type:`v4l2_control`.
151
152         If the event is generated due to a call to
153         :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or
154         :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the
155         event will *not* be sent to the file handle that called the ioctl
156         function. This prevents nasty feedback loops. If you *do* want to
157         get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
158         flag.
159
160         This event type will ensure that no information is lost when more
161         events are raised than there is room internally. In that case the
162         struct :c:type:`v4l2_event_ctrl` of the
163         second-oldest event is kept, but the ``changes`` field of the
164         second-oldest event is ORed with the ``changes`` field of the
165         oldest event.
166     * - ``V4L2_EVENT_FRAME_SYNC``
167       - 4
168       - Triggered immediately when the reception of a frame has begun.
169         This event has a struct
170         :c:type:`v4l2_event_frame_sync`
171         associated with it.
172
173         If the hardware needs to be stopped in the case of a buffer
174         underrun it might not be able to generate this event. In such
175         cases the ``frame_sequence`` field in struct
176         :c:type:`v4l2_event_frame_sync` will not
177         be incremented. This causes two consecutive frame sequence numbers
178         to have n times frame interval in between them.
179     * - ``V4L2_EVENT_SOURCE_CHANGE``
180       - 5
181       - This event is triggered when a source parameter change is detected
182         during runtime by the video device. It can be a runtime resolution
183         change triggered by a video decoder or the format change happening
184         on an input connector. This event requires that the ``id`` matches
185         the input index (when used with a video device node) or the pad
186         index (when used with a subdevice node) from which you want to
187         receive events.
188
189         This event has a struct
190         :c:type:`v4l2_event_src_change`
191         associated with it. The ``changes`` bitfield denotes what has
192         changed for the subscribed pad. If multiple events occurred before
193         application could dequeue them, then the changes will have the
194         ORed value of all the events generated.
195     * - ``V4L2_EVENT_MOTION_DET``
196       - 6
197       - Triggered whenever the motion detection state for one or more of
198         the regions changes. This event has a struct
199         :c:type:`v4l2_event_motion_det`
200         associated with it.
201     * - ``V4L2_EVENT_PRIVATE_START``
202       - 0x08000000
203       - Base event number for driver-private events.
204
205
206
207 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
208
209 .. c:type:: v4l2_event_vsync
210
211 .. flat-table:: struct v4l2_event_vsync
212     :header-rows:  0
213     :stub-columns: 0
214     :widths:       1 1 2
215
216     * - __u8
217       - ``field``
218       - The upcoming field. See enum :c:type:`v4l2_field`.
219
220
221
222 .. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}|
223
224 .. c:type:: v4l2_event_ctrl
225
226 .. flat-table:: struct v4l2_event_ctrl
227     :header-rows:  0
228     :stub-columns: 0
229     :widths:       1 1 2 1
230
231     * - __u32
232       - ``changes``
233       -
234       - A bitmask that tells what has changed. See
235         :ref:`ctrl-changes-flags`.
236     * - __u32
237       - ``type``
238       -
239       - The type of the control. See enum
240         :c:type:`v4l2_ctrl_type`.
241     * - union (anonymous)
242       -
243       -
244       -
245     * -
246       - __s32
247       - ``value``
248       - The 32-bit value of the control for 32-bit control types. This is
249         0 for string controls since the value of a string cannot be passed
250         using :ref:`VIDIOC_DQEVENT`.
251     * -
252       - __s64
253       - ``value64``
254       - The 64-bit value of the control for 64-bit control types.
255     * - __u32
256       - ``flags``
257       -
258       - The control flags. See :ref:`control-flags`.
259     * - __s32
260       - ``minimum``
261       -
262       - The minimum value of the control. See struct
263         :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
264     * - __s32
265       - ``maximum``
266       -
267       - The maximum value of the control. See struct
268         :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
269     * - __s32
270       - ``step``
271       -
272       - The step value of the control. See struct
273         :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
274     * - __s32
275       - ``default_value``
276       -
277       - The default value value of the control. See struct
278         :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
279
280
281
282 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
283
284 .. c:type:: v4l2_event_frame_sync
285
286 .. flat-table:: struct v4l2_event_frame_sync
287     :header-rows:  0
288     :stub-columns: 0
289     :widths:       1 1 2
290
291     * - __u32
292       - ``frame_sequence``
293       - The sequence number of the frame being received.
294
295
296
297 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
298
299 .. c:type:: v4l2_event_src_change
300
301 .. flat-table:: struct v4l2_event_src_change
302     :header-rows:  0
303     :stub-columns: 0
304     :widths:       1 1 2
305
306     * - __u32
307       - ``changes``
308       - A bitmask that tells what has changed. See
309         :ref:`src-changes-flags`.
310
311
312
313 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
314
315 .. c:type:: v4l2_event_motion_det
316
317 .. flat-table:: struct v4l2_event_motion_det
318     :header-rows:  0
319     :stub-columns: 0
320     :widths:       1 1 2
321
322     * - __u32
323       - ``flags``
324       - Currently only one flag is available: if
325         ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the
326         ``frame_sequence`` field is valid, otherwise that field should be
327         ignored.
328     * - __u32
329       - ``frame_sequence``
330       - The sequence number of the frame being received. Only valid if the
331         ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set.
332     * - __u32
333       - ``region_mask``
334       - The bitmask of the regions that reported motion. There is at least
335         one region. If this field is 0, then no motion was detected at
336         all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control
337         (see :ref:`detect-controls`) to assign a different region to
338         each cell in the motion detection grid, then that all cells are
339         automatically assigned to the default region 0.
340
341
342
343 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
344
345 .. _ctrl-changes-flags:
346
347 .. flat-table:: Control Changes
348     :header-rows:  0
349     :stub-columns: 0
350     :widths:       3 1 4
351
352     * - ``V4L2_EVENT_CTRL_CH_VALUE``
353       - 0x0001
354       - This control event was triggered because the value of the control
355         changed. Special cases: Volatile controls do no generate this
356         event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
357         flag set, then this event is sent as well, regardless its value.
358     * - ``V4L2_EVENT_CTRL_CH_FLAGS``
359       - 0x0002
360       - This control event was triggered because the control flags
361         changed.
362     * - ``V4L2_EVENT_CTRL_CH_RANGE``
363       - 0x0004
364       - This control event was triggered because the minimum, maximum,
365         step or the default value of the control changed.
366
367
368
369 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
370
371 .. _src-changes-flags:
372
373 .. flat-table:: Source Changes
374     :header-rows:  0
375     :stub-columns: 0
376     :widths:       3 1 4
377
378     * - ``V4L2_EVENT_SRC_CH_RESOLUTION``
379       - 0x0001
380       - This event gets triggered when a resolution change is detected at
381         an input. This can come from an input connector or from a video
382         decoder.
383
384
385 Return Value
386 ============
387
388 On success 0 is returned, on error -1 and the ``errno`` variable is set
389 appropriately. The generic error codes are described at the
390 :ref:`Generic Error Codes <gen-errors>` chapter.