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