Commit | Line | Data |
---|---|---|
82559ac0 MCC |
1 | .. Permission is granted to copy, distribute and/or modify this |
2 | .. document under the terms of the GNU Free Documentation License, | |
3 | .. Version 1.1 or any later version published by the Free Software | |
4 | .. Foundation, with no Invariant Sections, no Front-Cover Texts | |
5 | .. and no Back-Cover Texts. A copy of the license is included at | |
6 | .. Documentation/media/uapi/fdl-appendix.rst. | |
7 | .. | |
8 | .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections | |
9 | ||
5377d91f MH |
10 | .. _buffer: |
11 | ||
12 | ******* | |
13 | Buffers | |
14 | ******* | |
15 | ||
16 | A buffer contains data exchanged by application and driver using one of | |
17 | the Streaming I/O methods. In the multi-planar API, the data is held in | |
18 | planes, while the buffer structure acts as a container for the planes. | |
19 | Only pointers to buffers (planes) are exchanged, the data itself is not | |
20 | copied. These pointers, together with meta-information like timestamps | |
fc78c7c7 | 21 | or field parity, are stored in a struct :c:type:`v4l2_buffer`, |
7347081e | 22 | argument to the :ref:`VIDIOC_QUERYBUF`, |
59e18d7c | 23 | :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and |
af4a4d0d | 24 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API, |
fc78c7c7 | 25 | some plane-specific members of struct :c:type:`v4l2_buffer`, |
5377d91f | 26 | such as pointers and sizes for each plane, are stored in struct |
fc78c7c7 MCC |
27 | struct :c:type:`v4l2_plane` instead. In that case, struct |
28 | struct :c:type:`v4l2_buffer` contains an array of plane structures. | |
5377d91f MH |
29 | |
30 | Dequeued video buffers come with timestamps. The driver decides at which | |
31 | part of the frame and with which clock the timestamp is taken. Please | |
32 | see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and | |
33 | ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags | |
34 | are always valid and constant across all buffers during the whole video | |
35 | stream. Changes in these flags may take place as a side effect of | |
af4a4d0d MCC |
36 | :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or |
37 | :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The | |
5377d91f MH |
38 | ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on |
39 | mem-to-mem devices is an exception to the rule: the timestamp source | |
40 | flags are copied from the OUTPUT video buffer to the CAPTURE video | |
41 | buffer. | |
42 | ||
43 | ||
99bb078e LP |
44 | Interactions between formats, controls and buffers |
45 | ================================================== | |
46 | ||
47 | V4L2 exposes parameters that influence the buffer size, or the way data is | |
48 | laid out in the buffer. Those parameters are exposed through both formats and | |
49 | controls. One example of such a control is the ``V4L2_CID_ROTATE`` control | |
50 | that modifies the direction in which pixels are stored in the buffer, as well | |
51 | as the buffer size when the selected format includes padding at the end of | |
52 | lines. | |
53 | ||
54 | The set of information needed to interpret the content of a buffer (e.g. the | |
55 | pixel format, the line stride, the tiling orientation or the rotation) is | |
56 | collectively referred to in the rest of this section as the buffer layout. | |
57 | ||
aacfed85 HV |
58 | Controls that can modify the buffer layout shall set the |
59 | ``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag. | |
60 | ||
99bb078e LP |
61 | Modifying formats or controls that influence the buffer size or layout require |
62 | the stream to be stopped. Any attempt at such a modification while the stream | |
63 | is active shall cause the ioctl setting the format or the control to return | |
aacfed85 HV |
64 | the ``EBUSY`` error code. In that case drivers shall also set the |
65 | ``V4L2_CTRL_FLAG_GRABBED`` flag when calling | |
66 | :c:func:`VIDIOC_QUERYCTRL` or :c:func:`VIDIOC_QUERY_EXT_CTRL` for such a | |
67 | control while the stream is active. | |
99bb078e LP |
68 | |
69 | .. note:: | |
70 | ||
71 | The :c:func:`VIDIOC_S_SELECTION` ioctl can, depending on the hardware (for | |
72 | instance if the device doesn't include a scaler), modify the format in | |
73 | addition to the selection rectangle. Similarly, the | |
74 | :c:func:`VIDIOC_S_INPUT`, :c:func:`VIDIOC_S_OUTPUT`, :c:func:`VIDIOC_S_STD` | |
75 | and :c:func:`VIDIOC_S_DV_TIMINGS` ioctls can also modify the format and | |
76 | selection rectangles. When those ioctls result in a buffer size or layout | |
77 | change, drivers shall handle that condition as they would handle it in the | |
78 | :c:func:`VIDIOC_S_FMT` ioctl in all cases described in this section. | |
79 | ||
80 | Controls that only influence the buffer layout can be modified at any time | |
81 | when the stream is stopped. As they don't influence the buffer size, no | |
82 | special handling is needed to synchronize those controls with buffer | |
aacfed85 HV |
83 | allocation and the ``V4L2_CTRL_FLAG_GRABBED`` flag is cleared once the |
84 | stream is stopped. | |
99bb078e LP |
85 | |
86 | Formats and controls that influence the buffer size interact with buffer | |
87 | allocation. The simplest way to handle this is for drivers to always require | |
88 | buffers to be reallocated in order to change those formats or controls. In | |
89 | that case, to perform such changes, userspace applications shall first stop | |
90 | the video stream with the :c:func:`VIDIOC_STREAMOFF` ioctl if it is running | |
91 | and free all buffers with the :c:func:`VIDIOC_REQBUFS` ioctl if they are | |
aacfed85 HV |
92 | allocated. After freeing all buffers the ``V4L2_CTRL_FLAG_GRABBED`` flag |
93 | for controls is cleared. The format or controls can then be modified, and | |
94 | buffers shall then be reallocated and the stream restarted. A typical ioctl | |
95 | sequence is | |
99bb078e LP |
96 | |
97 | #. VIDIOC_STREAMOFF | |
98 | #. VIDIOC_REQBUFS(0) | |
99 | #. VIDIOC_S_EXT_CTRLS | |
100 | #. VIDIOC_S_FMT | |
101 | #. VIDIOC_REQBUFS(n) | |
102 | #. VIDIOC_QBUF | |
103 | #. VIDIOC_STREAMON | |
104 | ||
105 | The second :c:func:`VIDIOC_REQBUFS` call will take the new format and control | |
106 | value into account to compute the buffer size to allocate. Applications can | |
107 | also retrieve the size by calling the :c:func:`VIDIOC_G_FMT` ioctl if needed. | |
108 | ||
109 | .. note:: | |
110 | ||
111 | The API doesn't mandate the above order for control (3.) and format (4.) | |
112 | changes. Format and controls can be set in a different order, or even | |
113 | interleaved, depending on the device and use case. For instance some | |
114 | controls might behave differently for different pixel formats, in which | |
115 | case the format might need to be set first. | |
116 | ||
117 | When reallocation is required, any attempt to modify format or controls that | |
118 | influences the buffer size while buffers are allocated shall cause the format | |
119 | or control set ioctl to return the ``EBUSY`` error. Any attempt to queue a | |
120 | buffer too small for the current format or controls shall cause the | |
121 | :c:func:`VIDIOC_QBUF` ioctl to return a ``EINVAL`` error. | |
122 | ||
123 | Buffer reallocation is an expensive operation. To avoid that cost, drivers can | |
124 | (and are encouraged to) allow format or controls that influence the buffer | |
125 | size to be changed with buffers allocated. In that case, a typical ioctl | |
126 | sequence to modify format and controls is | |
127 | ||
128 | #. VIDIOC_STREAMOFF | |
129 | #. VIDIOC_S_EXT_CTRLS | |
130 | #. VIDIOC_S_FMT | |
131 | #. VIDIOC_QBUF | |
132 | #. VIDIOC_STREAMON | |
133 | ||
134 | For this sequence to operate correctly, queued buffers need to be large enough | |
135 | for the new format or controls. Drivers shall return a ``ENOSPC`` error in | |
136 | response to format change (:c:func:`VIDIOC_S_FMT`) or control changes | |
137 | (:c:func:`VIDIOC_S_CTRL` or :c:func:`VIDIOC_S_EXT_CTRLS`) if buffers too small | |
138 | for the new format are currently queued. As a simplification, drivers are | |
139 | allowed to return a ``EBUSY`` error from these ioctls if any buffer is | |
140 | currently queued, without checking the queued buffers sizes. | |
141 | ||
142 | Additionally, drivers shall return a ``EINVAL`` error from the | |
143 | :c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the | |
144 | current format or controls. Together, these requirements ensure that queued | |
145 | buffers will always be large enough for the configured format and controls. | |
146 | ||
147 | Userspace applications can query the buffer size required for a given format | |
148 | and controls by first setting the desired control values and then trying the | |
149 | desired format. The :c:func:`VIDIOC_TRY_FMT` ioctl will return the required | |
150 | buffer size. | |
151 | ||
152 | #. VIDIOC_S_EXT_CTRLS(x) | |
153 | #. VIDIOC_TRY_FMT() | |
154 | #. VIDIOC_S_EXT_CTRLS(y) | |
155 | #. VIDIOC_TRY_FMT() | |
156 | ||
157 | The :c:func:`VIDIOC_CREATE_BUFS` ioctl can then be used to allocate buffers | |
158 | based on the queried sizes (for instance by allocating a set of buffers large | |
159 | enough for all the desired formats and controls, or by allocating separate set | |
160 | of appropriately sized buffers for each use case). | |
161 | ||
162 | ||
e8be7e97 | 163 | .. c:type:: v4l2_buffer |
5377d91f | 164 | |
90865d29 MCC |
165 | struct v4l2_buffer |
166 | ================== | |
167 | ||
43e4138b | 168 | .. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.3cm}|p{10.5cm}| |
8b5efbeb MCC |
169 | |
170 | .. cssclass:: longtable | |
5bd4bb78 | 171 | |
5377d91f MH |
172 | .. flat-table:: struct v4l2_buffer |
173 | :header-rows: 0 | |
174 | :stub-columns: 0 | |
8b5efbeb | 175 | :widths: 1 2 1 10 |
5377d91f | 176 | |
c2b66caf LP |
177 | * - __u32 |
178 | - ``index`` | |
179 | - | |
180 | - Number of the buffer, set by the application except when calling | |
181 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the | |
182 | driver. This field can range from zero to the number of buffers | |
183 | allocated with the :ref:`VIDIOC_REQBUFS` ioctl | |
184 | (struct :c:type:`v4l2_requestbuffers` | |
185 | ``count``), plus any buffers allocated with | |
186 | :ref:`VIDIOC_CREATE_BUFS` minus one. | |
187 | * - __u32 | |
188 | - ``type`` | |
189 | - | |
190 | - Type of the buffer, same as struct | |
191 | :c:type:`v4l2_format` ``type`` or struct | |
192 | :c:type:`v4l2_requestbuffers` ``type``, set | |
193 | by the application. See :c:type:`v4l2_buf_type` | |
194 | * - __u32 | |
195 | - ``bytesused`` | |
196 | - | |
197 | - The number of bytes occupied by the data in the buffer. It depends | |
198 | on the negotiated data format and may change with each buffer for | |
199 | compressed variable size data like JPEG images. Drivers must set | |
200 | this field when ``type`` refers to a capture stream, applications | |
201 | when it refers to an output stream. If the application sets this | |
202 | to 0 for an output stream, then ``bytesused`` will be set to the | |
203 | size of the buffer (see the ``length`` field of this struct) by | |
204 | the driver. For multiplanar formats this field is ignored and the | |
205 | ``planes`` pointer is used instead. | |
206 | * - __u32 | |
207 | - ``flags`` | |
208 | - | |
209 | - Flags set by the application or driver, see :ref:`buffer-flags`. | |
210 | * - __u32 | |
211 | - ``field`` | |
212 | - | |
213 | - Indicates the field order of the image in the buffer, see | |
214 | :c:type:`v4l2_field`. This field is not used when the buffer | |
215 | contains VBI data. Drivers must set it when ``type`` refers to a | |
216 | capture stream, applications when it refers to an output stream. | |
217 | * - struct timeval | |
218 | - ``timestamp`` | |
219 | - | |
220 | - For capture streams this is time when the first data byte was | |
221 | captured, as returned by the :c:func:`clock_gettime()` function | |
222 | for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in | |
223 | :ref:`buffer-flags`. For output streams the driver stores the | |
224 | time at which the last data byte was actually sent out in the | |
225 | ``timestamp`` field. This permits applications to monitor the | |
226 | drift between the video and system clock. For output streams that | |
227 | use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill | |
228 | in the timestamp which will be copied by the driver to the capture | |
229 | stream. | |
230 | * - struct :c:type:`v4l2_timecode` | |
231 | - ``timecode`` | |
232 | - | |
233 | - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the | |
234 | ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this | |
235 | structure contains a frame timecode. In | |
236 | :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and | |
237 | bottom field contain the same timecode. Timecodes are intended to | |
238 | help video editing and are typically recorded on video tapes, but | |
239 | also embedded in compressed formats like MPEG. This field is | |
240 | independent of the ``timestamp`` and ``sequence`` fields. | |
241 | * - __u32 | |
242 | - ``sequence`` | |
243 | - | |
244 | - Set by the driver, counting the frames (not fields!) in sequence. | |
245 | This field is set for both input and output devices. | |
246 | * - :cspan:`3` | |
247 | ||
248 | In :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and | |
249 | bottom field have the same sequence number. The count starts at | |
250 | zero and includes dropped or repeated frames. A dropped frame was | |
251 | received by an input device but could not be stored due to lack of | |
252 | free buffer space. A repeated frame was displayed again by an | |
253 | output device because the application did not pass new data in | |
254 | time. | |
255 | ||
256 | .. note:: | |
257 | ||
258 | This may count the frames received e.g. over USB, without | |
259 | taking into account the frames dropped by the remote hardware due | |
260 | to limited compression throughput or bus bandwidth. These devices | |
261 | identify by not enumerating any video standards, see | |
262 | :ref:`standard`. | |
263 | ||
264 | * - __u32 | |
265 | - ``memory`` | |
266 | - | |
267 | - This field must be set by applications and/or drivers in | |
268 | accordance with the selected I/O method. See :c:type:`v4l2_memory` | |
269 | * - union | |
270 | - ``m`` | |
271 | * - | |
272 | - __u32 | |
273 | - ``offset`` | |
274 | - For the single-planar API and when ``memory`` is | |
275 | ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the | |
276 | start of the device memory. The value is returned by the driver | |
277 | and apart of serving as parameter to the | |
278 | :ref:`mmap() <func-mmap>` function not useful for applications. | |
279 | See :ref:`mmap` for details | |
280 | * - | |
281 | - unsigned long | |
282 | - ``userptr`` | |
283 | - For the single-planar API and when ``memory`` is | |
284 | ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to | |
285 | unsigned long type) in virtual memory, set by the application. See | |
286 | :ref:`userp` for details. | |
287 | * - | |
288 | - struct v4l2_plane | |
289 | - ``*planes`` | |
290 | - When using the multi-planar API, contains a userspace pointer to | |
291 | an array of struct :c:type:`v4l2_plane`. The size of | |
292 | the array should be put in the ``length`` field of this | |
293 | struct :c:type:`v4l2_buffer` structure. | |
294 | * - | |
295 | - int | |
296 | - ``fd`` | |
297 | - For the single-plane API and when ``memory`` is | |
298 | ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with | |
299 | a DMABUF buffer. | |
300 | * - __u32 | |
301 | - ``length`` | |
302 | - | |
303 | - Size of the buffer (not the payload) in bytes for the | |
304 | single-planar API. This is set by the driver based on the calls to | |
305 | :ref:`VIDIOC_REQBUFS` and/or | |
306 | :ref:`VIDIOC_CREATE_BUFS`. For the | |
307 | multi-planar API the application sets this to the number of | |
308 | elements in the ``planes`` array. The driver will fill in the | |
309 | actual number of valid elements in that array. | |
310 | * - __u32 | |
311 | - ``reserved2`` | |
312 | - | |
313 | - A place holder for future extensions. Drivers and applications | |
314 | must set this to 0. | |
315 | * - __u32 | |
cbb6a7f5 | 316 | - ``request_fd`` |
c2b66caf | 317 | - |
d4215edb HV |
318 | - The file descriptor of the request to queue the buffer to. If the flag |
319 | ``V4L2_BUF_FLAG_REQUEST_FD`` is set, then the buffer will be | |
320 | queued to this request. If the flag is not set, then this field will | |
321 | be ignored. | |
322 | ||
323 | The ``V4L2_BUF_FLAG_REQUEST_FD`` flag and this field are only used by | |
324 | :ref:`ioctl VIDIOC_QBUF <VIDIOC_QBUF>` and ignored by other ioctls that | |
325 | take a :c:type:`v4l2_buffer` as argument. | |
326 | ||
dc58a553 HV |
327 | Applications should not set ``V4L2_BUF_FLAG_REQUEST_FD`` for any ioctls |
328 | other than :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. | |
d4215edb | 329 | |
15cd442e | 330 | If the device does not support requests, then ``EACCES`` will be returned. |
34b41472 HV |
331 | If requests are supported but an invalid request file descriptor is |
332 | given, then ``EINVAL`` will be returned. | |
5377d91f MH |
333 | |
334 | ||
335 | ||
e8be7e97 | 336 | .. c:type:: v4l2_plane |
5377d91f | 337 | |
90865d29 MCC |
338 | struct v4l2_plane |
339 | ================= | |
340 | ||
5bd4bb78 MCC |
341 | .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| |
342 | ||
8b5efbeb MCC |
343 | .. cssclass:: longtable |
344 | ||
90865d29 | 345 | .. flat-table:: |
5377d91f MH |
346 | :header-rows: 0 |
347 | :stub-columns: 0 | |
348 | :widths: 1 1 1 2 | |
349 | ||
c2b66caf LP |
350 | * - __u32 |
351 | - ``bytesused`` | |
352 | - | |
353 | - The number of bytes occupied by data in the plane (its payload). | |
354 | Drivers must set this field when ``type`` refers to a capture | |
355 | stream, applications when it refers to an output stream. If the | |
356 | application sets this to 0 for an output stream, then | |
357 | ``bytesused`` will be set to the size of the plane (see the | |
358 | ``length`` field of this struct) by the driver. | |
359 | ||
360 | .. note:: | |
361 | ||
362 | Note that the actual image data starts at ``data_offset`` | |
363 | which may not be 0. | |
364 | * - __u32 | |
365 | - ``length`` | |
366 | - | |
367 | - Size in bytes of the plane (not its payload). This is set by the | |
368 | driver based on the calls to | |
369 | :ref:`VIDIOC_REQBUFS` and/or | |
370 | :ref:`VIDIOC_CREATE_BUFS`. | |
371 | * - union | |
372 | - ``m`` | |
373 | - | |
374 | - | |
375 | * - | |
376 | - __u32 | |
377 | - ``mem_offset`` | |
378 | - When the memory type in the containing struct | |
379 | :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this | |
380 | is the value that should be passed to :ref:`mmap() <func-mmap>`, | |
381 | similar to the ``offset`` field in struct | |
382 | :c:type:`v4l2_buffer`. | |
383 | * - | |
384 | - unsigned long | |
385 | - ``userptr`` | |
386 | - When the memory type in the containing struct | |
387 | :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``, | |
388 | this is a userspace pointer to the memory allocated for this plane | |
389 | by an application. | |
390 | * - | |
391 | - int | |
392 | - ``fd`` | |
393 | - When the memory type in the containing struct | |
394 | :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``, | |
395 | this is a file descriptor associated with a DMABUF buffer, similar | |
396 | to the ``fd`` field in struct :c:type:`v4l2_buffer`. | |
397 | * - __u32 | |
398 | - ``data_offset`` | |
399 | - | |
400 | - Offset in bytes to video data in the plane. Drivers must set this | |
401 | field when ``type`` refers to a capture stream, applications when | |
402 | it refers to an output stream. | |
403 | ||
404 | .. note:: | |
405 | ||
406 | That data_offset is included in ``bytesused``. So the | |
407 | size of the image in the plane is ``bytesused``-``data_offset`` | |
408 | at offset ``data_offset`` from the start of the plane. | |
409 | * - __u32 | |
410 | - ``reserved[11]`` | |
411 | - | |
412 | - Reserved for future use. Should be zeroed by drivers and | |
413 | applications. | |
5377d91f MH |
414 | |
415 | ||
416 | ||
56683d7d | 417 | .. c:type:: v4l2_buf_type |
5377d91f | 418 | |
90865d29 MCC |
419 | enum v4l2_buf_type |
420 | ================== | |
421 | ||
8b5efbeb MCC |
422 | .. cssclass:: longtable |
423 | ||
424 | .. tabularcolumns:: |p{7.2cm}|p{0.6cm}|p{9.7cm}| | |
5bd4bb78 | 425 | |
90865d29 | 426 | .. flat-table:: |
5377d91f MH |
427 | :header-rows: 0 |
428 | :stub-columns: 0 | |
8b5efbeb | 429 | :widths: 4 1 9 |
5377d91f | 430 | |
c2b66caf LP |
431 | * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` |
432 | - 1 | |
433 | - Buffer of a single-planar video capture stream, see | |
434 | :ref:`capture`. | |
435 | * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` | |
436 | - 9 | |
437 | - Buffer of a multi-planar video capture stream, see | |
438 | :ref:`capture`. | |
439 | * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` | |
440 | - 2 | |
441 | - Buffer of a single-planar video output stream, see | |
442 | :ref:`output`. | |
443 | * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` | |
444 | - 10 | |
445 | - Buffer of a multi-planar video output stream, see :ref:`output`. | |
446 | * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` | |
447 | - 3 | |
448 | - Buffer for video overlay, see :ref:`overlay`. | |
449 | * - ``V4L2_BUF_TYPE_VBI_CAPTURE`` | |
450 | - 4 | |
451 | - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`. | |
452 | * - ``V4L2_BUF_TYPE_VBI_OUTPUT`` | |
453 | - 5 | |
454 | - Buffer of a raw VBI output stream, see :ref:`raw-vbi`. | |
455 | * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` | |
456 | - 6 | |
457 | - Buffer of a sliced VBI capture stream, see :ref:`sliced`. | |
458 | * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` | |
459 | - 7 | |
460 | - Buffer of a sliced VBI output stream, see :ref:`sliced`. | |
461 | * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` | |
462 | - 8 | |
463 | - Buffer for video output overlay (OSD), see :ref:`osd`. | |
464 | * - ``V4L2_BUF_TYPE_SDR_CAPTURE`` | |
465 | - 11 | |
466 | - Buffer for Software Defined Radio (SDR) capture stream, see | |
467 | :ref:`sdr`. | |
468 | * - ``V4L2_BUF_TYPE_SDR_OUTPUT`` | |
469 | - 12 | |
470 | - Buffer for Software Defined Radio (SDR) output stream, see | |
471 | :ref:`sdr`. | |
fb9ffa6a LP |
472 | * - ``V4L2_BUF_TYPE_META_CAPTURE`` |
473 | - 13 | |
474 | - Buffer for metadata capture, see :ref:`metadata`. | |
934a040b SA |
475 | * - ``V4L2_BUF_TYPE_META_OUTPUT`` |
476 | - 14 | |
477 | - Buffer for metadata output, see :ref:`metadata`. | |
5377d91f MH |
478 | |
479 | ||
480 | ||
481 | .. _buffer-flags: | |
482 | ||
90865d29 MCC |
483 | Buffer Flags |
484 | ============ | |
485 | ||
8b5efbeb MCC |
486 | .. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}| |
487 | ||
488 | .. cssclass:: longtable | |
5bd4bb78 | 489 | |
90865d29 | 490 | .. flat-table:: |
5377d91f MH |
491 | :header-rows: 0 |
492 | :stub-columns: 0 | |
493 | :widths: 3 1 4 | |
494 | ||
c2b66caf LP |
495 | * .. _`V4L2-BUF-FLAG-MAPPED`: |
496 | ||
497 | - ``V4L2_BUF_FLAG_MAPPED`` | |
498 | - 0x00000001 | |
499 | - The buffer resides in device memory and has been mapped into the | |
500 | application's address space, see :ref:`mmap` for details. | |
501 | Drivers set or clear this flag when the | |
502 | :ref:`VIDIOC_QUERYBUF`, | |
503 | :ref:`VIDIOC_QBUF` or | |
504 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the | |
505 | driver. | |
506 | * .. _`V4L2-BUF-FLAG-QUEUED`: | |
507 | ||
508 | - ``V4L2_BUF_FLAG_QUEUED`` | |
509 | - 0x00000002 | |
510 | - Internally drivers maintain two buffer queues, an incoming and | |
511 | outgoing queue. When this flag is set, the buffer is currently on | |
512 | the incoming queue. It automatically moves to the outgoing queue | |
513 | after the buffer has been filled (capture devices) or displayed | |
514 | (output devices). Drivers set or clear this flag when the | |
515 | ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling | |
516 | the ``VIDIOC_QBUF``\ ioctl it is always set and after | |
517 | ``VIDIOC_DQBUF`` always cleared. | |
518 | * .. _`V4L2-BUF-FLAG-DONE`: | |
519 | ||
520 | - ``V4L2_BUF_FLAG_DONE`` | |
521 | - 0x00000004 | |
522 | - When this flag is set, the buffer is currently on the outgoing | |
523 | queue, ready to be dequeued from the driver. Drivers set or clear | |
524 | this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After | |
525 | calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always | |
526 | cleared. Of course a buffer cannot be on both queues at the same | |
527 | time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag | |
528 | are mutually exclusive. They can be both cleared however, then the | |
529 | buffer is in "dequeued" state, in the application domain so to | |
530 | say. | |
531 | * .. _`V4L2-BUF-FLAG-ERROR`: | |
532 | ||
533 | - ``V4L2_BUF_FLAG_ERROR`` | |
534 | - 0x00000040 | |
535 | - When this flag is set, the buffer has been dequeued successfully, | |
536 | although the data might have been corrupted. This is recoverable, | |
537 | streaming may continue as normal and the buffer may be reused | |
538 | normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is | |
539 | called. | |
cbb6a7f5 AC |
540 | * .. _`V4L2-BUF-FLAG-IN-REQUEST`: |
541 | ||
542 | - ``V4L2_BUF_FLAG_IN_REQUEST`` | |
543 | - 0x00000080 | |
544 | - This buffer is part of a request that hasn't been queued yet. | |
c2b66caf LP |
545 | * .. _`V4L2-BUF-FLAG-KEYFRAME`: |
546 | ||
547 | - ``V4L2_BUF_FLAG_KEYFRAME`` | |
548 | - 0x00000008 | |
549 | - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF`` | |
550 | ioctl. It may be set by video capture devices when the buffer | |
551 | contains a compressed image which is a key frame (or field), i. e. | |
552 | can be decompressed on its own. Also known as an I-frame. | |
553 | Applications can set this bit when ``type`` refers to an output | |
554 | stream. | |
555 | * .. _`V4L2-BUF-FLAG-PFRAME`: | |
556 | ||
557 | - ``V4L2_BUF_FLAG_PFRAME`` | |
558 | - 0x00000010 | |
559 | - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames | |
560 | or fields which contain only differences to a previous key frame. | |
561 | Applications can set this bit when ``type`` refers to an output | |
562 | stream. | |
563 | * .. _`V4L2-BUF-FLAG-BFRAME`: | |
564 | ||
565 | - ``V4L2_BUF_FLAG_BFRAME`` | |
566 | - 0x00000020 | |
567 | - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional | |
568 | predicted frame or field which contains only the differences | |
569 | between the current frame and both the preceding and following key | |
570 | frames to specify its content. Applications can set this bit when | |
571 | ``type`` refers to an output stream. | |
572 | * .. _`V4L2-BUF-FLAG-TIMECODE`: | |
573 | ||
574 | - ``V4L2_BUF_FLAG_TIMECODE`` | |
575 | - 0x00000100 | |
576 | - The ``timecode`` field is valid. Drivers set or clear this flag | |
577 | when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set | |
578 | this bit and the corresponding ``timecode`` structure when | |
579 | ``type`` refers to an output stream. | |
580 | * .. _`V4L2-BUF-FLAG-PREPARED`: | |
581 | ||
582 | - ``V4L2_BUF_FLAG_PREPARED`` | |
583 | - 0x00000400 | |
584 | - The buffer has been prepared for I/O and can be queued by the | |
585 | application. Drivers set or clear this flag when the | |
586 | :ref:`VIDIOC_QUERYBUF`, | |
587 | :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`, | |
588 | :ref:`VIDIOC_QBUF` or | |
589 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. | |
590 | * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: | |
591 | ||
592 | - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` | |
593 | - 0x00000800 | |
594 | - Caches do not have to be invalidated for this buffer. Typically | |
595 | applications shall use this flag if the data captured in the | |
596 | buffer is not going to be touched by the CPU, instead the buffer | |
597 | will, probably, be passed on to a DMA-capable hardware unit for | |
598 | further processing or output. | |
599 | * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`: | |
600 | ||
601 | - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` | |
602 | - 0x00001000 | |
603 | - Caches do not have to be cleaned for this buffer. Typically | |
604 | applications shall use this flag for output buffers if the data in | |
605 | this buffer has not been created by the CPU but by some | |
606 | DMA-capable unit, in which case caches have not been used. | |
607 | * .. _`V4L2-BUF-FLAG-LAST`: | |
608 | ||
609 | - ``V4L2_BUF_FLAG_LAST`` | |
610 | - 0x00100000 | |
611 | - Last buffer produced by the hardware. mem2mem codec drivers set | |
612 | this flag on the capture queue for the last buffer when the | |
613 | :ref:`VIDIOC_QUERYBUF` or | |
614 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to | |
615 | hardware limitations, the last buffer may be empty. In this case | |
616 | the driver will set the ``bytesused`` field to 0, regardless of | |
617 | the format. Any Any subsequent call to the | |
618 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, | |
619 | but return an ``EPIPE`` error code. | |
cbb6a7f5 AC |
620 | * .. _`V4L2-BUF-FLAG-REQUEST-FD`: |
621 | ||
622 | - ``V4L2_BUF_FLAG_REQUEST_FD`` | |
623 | - 0x00800000 | |
624 | - The ``request_fd`` field contains a valid file descriptor. | |
c2b66caf LP |
625 | * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`: |
626 | ||
627 | - ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` | |
628 | - 0x0000e000 | |
629 | - Mask for timestamp types below. To test the timestamp type, mask | |
630 | out bits not belonging to timestamp type by performing a logical | |
631 | and operation with buffer flags and timestamp mask. | |
632 | * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`: | |
633 | ||
634 | - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN`` | |
635 | - 0x00000000 | |
636 | - Unknown timestamp type. This type is used by drivers before Linux | |
637 | 3.9 and may be either monotonic (see below) or realtime (wall | |
638 | clock). Monotonic clock has been favoured in embedded systems | |
639 | whereas most of the drivers use the realtime clock. Either kinds | |
640 | of timestamps are available in user space via | |
641 | :c:func:`clock_gettime` using clock IDs ``CLOCK_MONOTONIC`` | |
642 | and ``CLOCK_REALTIME``, respectively. | |
643 | * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`: | |
644 | ||
645 | - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC`` | |
646 | - 0x00002000 | |
647 | - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC`` | |
648 | clock. To access the same clock outside V4L2, use | |
649 | :c:func:`clock_gettime`. | |
650 | * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`: | |
651 | ||
652 | - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` | |
653 | - 0x00004000 | |
654 | - The CAPTURE buffer timestamp has been taken from the corresponding | |
655 | OUTPUT buffer. This flag applies only to mem2mem devices. | |
656 | * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`: | |
657 | ||
658 | - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` | |
659 | - 0x00070000 | |
660 | - Mask for timestamp sources below. The timestamp source defines the | |
661 | point of time the timestamp is taken in relation to the frame. | |
662 | Logical 'and' operation between the ``flags`` field and | |
663 | ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the | |
664 | timestamp source. Applications must set the timestamp source when | |
665 | ``type`` refers to an output stream and | |
666 | ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set. | |
667 | * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`: | |
668 | ||
669 | - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF`` | |
670 | - 0x00000000 | |
671 | - End Of Frame. The buffer timestamp has been taken when the last | |
672 | pixel of the frame has been received or the last pixel of the | |
673 | frame has been transmitted. In practice, software generated | |
674 | timestamps will typically be read from the clock a small amount of | |
675 | time after the last pixel has been received or transmitten, | |
676 | depending on the system and other activity in it. | |
677 | * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`: | |
678 | ||
679 | - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE`` | |
680 | - 0x00010000 | |
681 | - Start Of Exposure. The buffer timestamp has been taken when the | |
682 | exposure of the frame has begun. This is only valid for the | |
683 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. | |
5377d91f MH |
684 | |
685 | ||
686 | ||
56683d7d | 687 | .. c:type:: v4l2_memory |
5377d91f | 688 | |
90865d29 MCC |
689 | enum v4l2_memory |
690 | ================ | |
691 | ||
5bd4bb78 MCC |
692 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
693 | ||
90865d29 | 694 | .. flat-table:: |
5377d91f MH |
695 | :header-rows: 0 |
696 | :stub-columns: 0 | |
697 | :widths: 3 1 4 | |
698 | ||
c2b66caf LP |
699 | * - ``V4L2_MEMORY_MMAP`` |
700 | - 1 | |
701 | - The buffer is used for :ref:`memory mapping <mmap>` I/O. | |
702 | * - ``V4L2_MEMORY_USERPTR`` | |
703 | - 2 | |
704 | - The buffer is used for :ref:`user pointer <userp>` I/O. | |
705 | * - ``V4L2_MEMORY_OVERLAY`` | |
706 | - 3 | |
707 | - [to do] | |
708 | * - ``V4L2_MEMORY_DMABUF`` | |
709 | - 4 | |
710 | - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O. | |
5377d91f MH |
711 | |
712 | ||
713 | ||
714 | Timecodes | |
715 | ========= | |
716 | ||
fc78c7c7 | 717 | The struct :c:type:`v4l2_timecode` structure is designed to hold a |
5377d91f | 718 | :ref:`smpte12m` or similar timecode. (struct |
a17a954e | 719 | struct :c:type:`timeval` timestamps are stored in struct |
e8be7e97 | 720 | :c:type:`v4l2_buffer` field ``timestamp``.) |
5377d91f MH |
721 | |
722 | ||
e8be7e97 | 723 | .. c:type:: v4l2_timecode |
5377d91f | 724 | |
90865d29 MCC |
725 | struct v4l2_timecode |
726 | -------------------- | |
727 | ||
5bd4bb78 MCC |
728 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
729 | ||
90865d29 | 730 | .. flat-table:: |
5377d91f MH |
731 | :header-rows: 0 |
732 | :stub-columns: 0 | |
733 | :widths: 1 1 2 | |
734 | ||
c2b66caf LP |
735 | * - __u32 |
736 | - ``type`` | |
737 | - Frame rate the timecodes are based on, see :ref:`timecode-type`. | |
738 | * - __u32 | |
739 | - ``flags`` | |
740 | - Timecode flags, see :ref:`timecode-flags`. | |
741 | * - __u8 | |
742 | - ``frames`` | |
743 | - Frame count, 0 ... 23/24/29/49/59, depending on the type of | |
744 | timecode. | |
745 | * - __u8 | |
746 | - ``seconds`` | |
747 | - Seconds count, 0 ... 59. This is a binary, not BCD number. | |
748 | * - __u8 | |
749 | - ``minutes`` | |
750 | - Minutes count, 0 ... 59. This is a binary, not BCD number. | |
751 | * - __u8 | |
752 | - ``hours`` | |
753 | - Hours count, 0 ... 29. This is a binary, not BCD number. | |
754 | * - __u8 | |
755 | - ``userbits``\ [4] | |
756 | - The "user group" bits from the timecode. | |
5377d91f MH |
757 | |
758 | ||
759 | ||
760 | .. _timecode-type: | |
761 | ||
90865d29 MCC |
762 | Timecode Types |
763 | -------------- | |
764 | ||
5bd4bb78 MCC |
765 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
766 | ||
90865d29 | 767 | .. flat-table:: |
5377d91f MH |
768 | :header-rows: 0 |
769 | :stub-columns: 0 | |
770 | :widths: 3 1 4 | |
771 | ||
c2b66caf LP |
772 | * - ``V4L2_TC_TYPE_24FPS`` |
773 | - 1 | |
774 | - 24 frames per second, i. e. film. | |
775 | * - ``V4L2_TC_TYPE_25FPS`` | |
776 | - 2 | |
777 | - 25 frames per second, i. e. PAL or SECAM video. | |
778 | * - ``V4L2_TC_TYPE_30FPS`` | |
779 | - 3 | |
780 | - 30 frames per second, i. e. NTSC video. | |
781 | * - ``V4L2_TC_TYPE_50FPS`` | |
782 | - 4 | |
783 | - | |
784 | * - ``V4L2_TC_TYPE_60FPS`` | |
785 | - 5 | |
786 | - | |
5377d91f MH |
787 | |
788 | ||
789 | ||
790 | .. _timecode-flags: | |
791 | ||
90865d29 MCC |
792 | Timecode Flags |
793 | -------------- | |
794 | ||
8b5efbeb | 795 | .. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}| |
5bd4bb78 | 796 | |
90865d29 | 797 | .. flat-table:: |
5377d91f MH |
798 | :header-rows: 0 |
799 | :stub-columns: 0 | |
800 | :widths: 3 1 4 | |
801 | ||
c2b66caf LP |
802 | * - ``V4L2_TC_FLAG_DROPFRAME`` |
803 | - 0x0001 | |
804 | - Indicates "drop frame" semantics for counting frames in 29.97 fps | |
805 | material. When set, frame numbers 0 and 1 at the start of each | |
806 | minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the | |
807 | count. | |
808 | * - ``V4L2_TC_FLAG_COLORFRAME`` | |
809 | - 0x0002 | |
810 | - The "color frame" flag. | |
811 | * - ``V4L2_TC_USERBITS_field`` | |
812 | - 0x000C | |
813 | - Field mask for the "binary group flags". | |
814 | * - ``V4L2_TC_USERBITS_USERDEFINED`` | |
815 | - 0x0000 | |
816 | - Unspecified format. | |
817 | * - ``V4L2_TC_USERBITS_8BITCHARS`` | |
818 | - 0x0008 | |
819 | - 8-bit ISO characters. |