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