Documentation/media/uapi/v4l/buffer.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _buffer:
   4
   5 *******
   6 Buffers
   7 *******
   8
   9 A buffer contains data exchanged by application and driver using one of
  10 the Streaming I/O methods. In the multi-planar API, the data is held in
  11 planes, while the buffer structure acts as a container for the planes.
  12 Only pointers to buffers (planes) are exchanged, the data itself is not
  13 copied. These pointers, together with meta-information like timestamps
  14 or field parity, are stored in a struct :c:type:`v4l2_buffer`,
  15 argument to the :ref:`VIDIOC_QUERYBUF`,
  16 :ref:`VIDIOC_QBUF` and
  17 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API,
  18 some plane-specific members of struct :c:type:`v4l2_buffer`,
  19 such as pointers and sizes for each plane, are stored in struct
  20 struct :c:type:`v4l2_plane` instead. In that case, struct
  21 struct :c:type:`v4l2_buffer` contains an array of plane structures.
  22
  23 Dequeued video buffers come with timestamps. The driver decides at which
  24 part of the frame and with which clock the timestamp is taken. Please
  25 see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and
  26 ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags
  27 are always valid and constant across all buffers during the whole video
  28 stream. Changes in these flags may take place as a side effect of
  29 :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or
  30 :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The
  31 ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on
  32 mem-to-mem devices is an exception to the rule: the timestamp source
  33 flags are copied from the OUTPUT video buffer to the CAPTURE video
  34 buffer.
  35
  36
  37 .. c:type:: v4l2_buffer
  38
  39 struct v4l2_buffer
  40 ==================
  41
  42 .. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.3cm}|p{10.5cm}|
  43
  44 .. cssclass:: longtable
  45
  46 .. flat-table:: struct v4l2_buffer
  47     :header-rows:  0
  48     :stub-columns: 0
  49     :widths:       1 2 1 10
  50
  51
  52     -  .. row 1
  53
  54        -  __u32
  55
  56        -  ``index``
  57
  58        -
  59        -  Number of the buffer, set by the application except when calling
  60           :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the
  61           driver. This field can range from zero to the number of buffers
  62           allocated with the :ref:`VIDIOC_REQBUFS` ioctl
  63           (struct :c:type:`v4l2_requestbuffers`
  64           ``count``), plus any buffers allocated with
  65           :ref:`VIDIOC_CREATE_BUFS` minus one.
  66
  67     -  .. row 2
  68
  69        -  __u32
  70
  71        -  ``type``
  72
  73        -
  74        -  Type of the buffer, same as struct
  75           :c:type:`v4l2_format` ``type`` or struct
  76           :c:type:`v4l2_requestbuffers` ``type``, set
  77           by the application. See :ref:`v4l2-buf-type`
  78
  79     -  .. row 3
  80
  81        -  __u32
  82
  83        -  ``bytesused``
  84
  85        -
  86        -  The number of bytes occupied by the data in the buffer. It depends
  87           on the negotiated data format and may change with each buffer for
  88           compressed variable size data like JPEG images. Drivers must set
  89           this field when ``type`` refers to a capture stream, applications
  90           when it refers to an output stream. If the application sets this
  91           to 0 for an output stream, then ``bytesused`` will be set to the
  92           size of the buffer (see the ``length`` field of this struct) by
  93           the driver. For multiplanar formats this field is ignored and the
  94           ``planes`` pointer is used instead.
  95
  96     -  .. row 4
  97
  98        -  __u32
  99
 100        -  ``flags``
 101
 102        -
 103        -  Flags set by the application or driver, see :ref:`buffer-flags`.
 104
 105     -  .. row 5
 106
 107        -  __u32
 108
 109        -  ``field``
 110
 111        -
 112        -  Indicates the field order of the image in the buffer, see
 113           :ref:`v4l2-field`. This field is not used when the buffer
 114           contains VBI data. Drivers must set it when ``type`` refers to a
 115           capture stream, applications when it refers to an output stream.
 116
 117     -  .. row 6
 118
 119        -  struct timeval
 120
 121        -  ``timestamp``
 122
 123        -
 124        -  For capture streams this is time when the first data byte was
 125           captured, as returned by the :c:func:`clock_gettime()` function
 126           for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in
 127           :ref:`buffer-flags`. For output streams the driver stores the
 128           time at which the last data byte was actually sent out in the
 129           ``timestamp`` field. This permits applications to monitor the
 130           drift between the video and system clock. For output streams that
 131           use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill
 132           in the timestamp which will be copied by the driver to the capture
 133           stream.
 134
 135     -  .. row 7
 136
 137        -  struct :c:type:`v4l2_timecode`
 138
 139        -  ``timecode``
 140
 141        -
 142        -  When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the
 143           ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
 144           structure contains a frame timecode. In
 145           :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
 146           bottom field contain the same timecode. Timecodes are intended to
 147           help video editing and are typically recorded on video tapes, but
 148           also embedded in compressed formats like MPEG. This field is
 149           independent of the ``timestamp`` and ``sequence`` fields.
 150
 151     -  .. row 8
 152
 153        -  __u32
 154
 155        -  ``sequence``
 156
 157        -
 158        -  Set by the driver, counting the frames (not fields!) in sequence.
 159           This field is set for both input and output devices.
 160
 161     -  .. row 9
 162
 163        -  :cspan:`3`
 164
 165           In :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
 166           bottom field have the same sequence number. The count starts at
 167           zero and includes dropped or repeated frames. A dropped frame was
 168           received by an input device but could not be stored due to lack of
 169           free buffer space. A repeated frame was displayed again by an
 170           output device because the application did not pass new data in
 171           time.
 172
 173           .. note::
 174
 175              This may count the frames received e.g. over USB, without
 176              taking into account the frames dropped by the remote hardware due
 177              to limited compression throughput or bus bandwidth. These devices
 178              identify by not enumerating any video standards, see
 179              :ref:`standard`.
 180
 181
 182     -  .. row 10
 183
 184        -  __u32
 185
 186        -  ``memory``
 187
 188        -
 189        -  This field must be set by applications and/or drivers in
 190           accordance with the selected I/O method. See :ref:`v4l2-memory`
 191
 192     -  .. row 11
 193
 194        -  union
 195
 196        -  ``m``
 197
 198     -  .. row 12
 199
 200        -
 201        -  __u32
 202
 203        -  ``offset``
 204
 205        -  For the single-planar API and when ``memory`` is
 206           ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
 207           start of the device memory. The value is returned by the driver
 208           and apart of serving as parameter to the
 209           :ref:`mmap() <func-mmap>` function not useful for applications.
 210           See :ref:`mmap` for details
 211
 212     -  .. row 13
 213
 214        -
 215        -  unsigned long
 216
 217        -  ``userptr``
 218
 219        -  For the single-planar API and when ``memory`` is
 220           ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
 221           unsigned long type) in virtual memory, set by the application. See
 222           :ref:`userp` for details.
 223
 224     -  .. row 14
 225
 226        -
 227        -  struct v4l2_plane
 228
 229        -  ``*planes``
 230
 231        -  When using the multi-planar API, contains a userspace pointer to
 232           an array of struct :c:type:`v4l2_plane`. The size of
 233           the array should be put in the ``length`` field of this
 234           struct :c:type:`v4l2_buffer` structure.
 235
 236     -  .. row 15
 237
 238        -
 239        -  int
 240
 241        -  ``fd``
 242
 243        -  For the single-plane API and when ``memory`` is
 244           ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with
 245           a DMABUF buffer.
 246
 247     -  .. row 16
 248
 249        -  __u32
 250
 251        -  ``length``
 252
 253        -
 254        -  Size of the buffer (not the payload) in bytes for the
 255           single-planar API. This is set by the driver based on the calls to
 256           :ref:`VIDIOC_REQBUFS` and/or
 257           :ref:`VIDIOC_CREATE_BUFS`. For the
 258           multi-planar API the application sets this to the number of
 259           elements in the ``planes`` array. The driver will fill in the
 260           actual number of valid elements in that array.
 261
 262     -  .. row 17
 263
 264        -  __u32
 265
 266        -  ``reserved2``
 267
 268        -
 269        -  A place holder for future extensions. Drivers and applications
 270           must set this to 0.
 271
 272     -  .. row 18
 273
 274        -  __u32
 275
 276        -  ``reserved``
 277
 278        -
 279        -  A place holder for future extensions. Drivers and applications
 280           must set this to 0.
 281
 282
 283
 284 .. c:type:: v4l2_plane
 285
 286 struct v4l2_plane
 287 =================
 288
 289 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
 290
 291 .. cssclass:: longtable
 292
 293 .. flat-table::
 294     :header-rows:  0
 295     :stub-columns: 0
 296     :widths:       1 1 1 2
 297
 298
 299     -  .. row 1
 300
 301        -  __u32
 302
 303        -  ``bytesused``
 304
 305        -
 306        -  The number of bytes occupied by data in the plane (its payload).
 307           Drivers must set this field when ``type`` refers to a capture
 308           stream, applications when it refers to an output stream. If the
 309           application sets this to 0 for an output stream, then
 310           ``bytesused`` will be set to the size of the plane (see the
 311           ``length`` field of this struct) by the driver.
 312
 313           .. note::
 314
 315              Note that the actual image data starts at ``data_offset``
 316              which may not be 0.
 317
 318     -  .. row 2
 319
 320        -  __u32
 321
 322        -  ``length``
 323
 324        -
 325        -  Size in bytes of the plane (not its payload). This is set by the
 326           driver based on the calls to
 327           :ref:`VIDIOC_REQBUFS` and/or
 328           :ref:`VIDIOC_CREATE_BUFS`.
 329
 330     -  .. row 3
 331
 332        -  union
 333
 334        -  ``m``
 335
 336        -
 337        -
 338
 339     -  .. row 4
 340
 341        -
 342        -  __u32
 343
 344        -  ``mem_offset``
 345
 346        -  When the memory type in the containing struct
 347           :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this
 348           is the value that should be passed to :ref:`mmap() <func-mmap>`,
 349           similar to the ``offset`` field in struct
 350           :c:type:`v4l2_buffer`.
 351
 352     -  .. row 5
 353
 354        -
 355        -  unsigned long
 356
 357        -  ``userptr``
 358
 359        -  When the memory type in the containing struct
 360           :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``,
 361           this is a userspace pointer to the memory allocated for this plane
 362           by an application.
 363
 364     -  .. row 6
 365
 366        -
 367        -  int
 368
 369        -  ``fd``
 370
 371        -  When the memory type in the containing struct
 372           :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``,
 373           this is a file descriptor associated with a DMABUF buffer, similar
 374           to the ``fd`` field in struct :c:type:`v4l2_buffer`.
 375
 376     -  .. row 7
 377
 378        -  __u32
 379
 380        -  ``data_offset``
 381
 382        -
 383        -  Offset in bytes to video data in the plane. Drivers must set this
 384           field when ``type`` refers to a capture stream, applications when
 385           it refers to an output stream.
 386
 387           .. note::
 388
 389              That data_offset is included  in ``bytesused``. So the
 390              size of the image in the plane is ``bytesused``-``data_offset``
 391              at offset ``data_offset`` from the start of the plane.
 392
 393     -  .. row 8
 394
 395        -  __u32
 396
 397        -  ``reserved[11]``
 398
 399        -
 400        -  Reserved for future use. Should be zeroed by drivers and
 401           applications.
 402
 403
 404
 405 .. _v4l2-buf-type:
 406
 407 enum v4l2_buf_type
 408 ==================
 409
 410 .. cssclass:: longtable
 411
 412 .. tabularcolumns:: |p{7.2cm}|p{0.6cm}|p{9.7cm}|
 413
 414 .. flat-table::
 415     :header-rows:  0
 416     :stub-columns: 0
 417     :widths:       4 1 9
 418
 419
 420     -  .. row 1
 421
 422        -  ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
 423
 424        -  1
 425
 426        -  Buffer of a single-planar video capture stream, see
 427           :ref:`capture`.
 428
 429     -  .. row 2
 430
 431        -  ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
 432
 433        -  9
 434
 435        -  Buffer of a multi-planar video capture stream, see
 436           :ref:`capture`.
 437
 438     -  .. row 3
 439
 440        -  ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
 441
 442        -  2
 443
 444        -  Buffer of a single-planar video output stream, see
 445           :ref:`output`.
 446
 447     -  .. row 4
 448
 449        -  ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
 450
 451        -  10
 452
 453        -  Buffer of a multi-planar video output stream, see :ref:`output`.
 454
 455     -  .. row 5
 456
 457        -  ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
 458
 459        -  3
 460
 461        -  Buffer for video overlay, see :ref:`overlay`.
 462
 463     -  .. row 6
 464
 465        -  ``V4L2_BUF_TYPE_VBI_CAPTURE``
 466
 467        -  4
 468
 469        -  Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
 470
 471     -  .. row 7
 472
 473        -  ``V4L2_BUF_TYPE_VBI_OUTPUT``
 474
 475        -  5
 476
 477        -  Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
 478
 479     -  .. row 8
 480
 481        -  ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
 482
 483        -  6
 484
 485        -  Buffer of a sliced VBI capture stream, see :ref:`sliced`.
 486
 487     -  .. row 9
 488
 489        -  ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
 490
 491        -  7
 492
 493        -  Buffer of a sliced VBI output stream, see :ref:`sliced`.
 494
 495     -  .. row 10
 496
 497        -  ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
 498
 499        -  8
 500
 501        -  Buffer for video output overlay (OSD), see :ref:`osd`.
 502
 503     -  .. row 11
 504
 505        -  ``V4L2_BUF_TYPE_SDR_CAPTURE``
 506
 507        -  11
 508
 509        -  Buffer for Software Defined Radio (SDR) capture stream, see
 510           :ref:`sdr`.
 511
 512     -  .. row 12
 513
 514        -  ``V4L2_BUF_TYPE_SDR_OUTPUT``
 515
 516        -  12
 517
 518        -  Buffer for Software Defined Radio (SDR) output stream, see
 519           :ref:`sdr`.
 520
 521
 522
 523 .. _buffer-flags:
 524
 525 Buffer Flags
 526 ============
 527
 528 .. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}|
 529
 530 .. cssclass:: longtable
 531
 532 .. flat-table::
 533     :header-rows:  0
 534     :stub-columns: 0
 535     :widths:       3 1 4
 536
 537
 538     -  .. _`V4L2-BUF-FLAG-MAPPED`:
 539
 540        -  ``V4L2_BUF_FLAG_MAPPED``
 541
 542        -  0x00000001
 543
 544        -  The buffer resides in device memory and has been mapped into the
 545           application's address space, see :ref:`mmap` for details.
 546           Drivers set or clear this flag when the
 547           :ref:`VIDIOC_QUERYBUF`,
 548           :ref:`VIDIOC_QBUF` or
 549           :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the
 550           driver.
 551
 552     -  .. _`V4L2-BUF-FLAG-QUEUED`:
 553
 554        -  ``V4L2_BUF_FLAG_QUEUED``
 555
 556        -  0x00000002
 557
 558        -  Internally drivers maintain two buffer queues, an incoming and
 559           outgoing queue. When this flag is set, the buffer is currently on
 560           the incoming queue. It automatically moves to the outgoing queue
 561           after the buffer has been filled (capture devices) or displayed
 562           (output devices). Drivers set or clear this flag when the
 563           ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling
 564           the ``VIDIOC_QBUF``\ ioctl it is always set and after
 565           ``VIDIOC_DQBUF`` always cleared.
 566
 567     -  .. _`V4L2-BUF-FLAG-DONE`:
 568
 569        -  ``V4L2_BUF_FLAG_DONE``
 570
 571        -  0x00000004
 572
 573        -  When this flag is set, the buffer is currently on the outgoing
 574           queue, ready to be dequeued from the driver. Drivers set or clear
 575           this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After
 576           calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always
 577           cleared. Of course a buffer cannot be on both queues at the same
 578           time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag
 579           are mutually exclusive. They can be both cleared however, then the
 580           buffer is in "dequeued" state, in the application domain so to
 581           say.
 582
 583     -  .. _`V4L2-BUF-FLAG-ERROR`:
 584
 585        -  ``V4L2_BUF_FLAG_ERROR``
 586
 587        -  0x00000040
 588
 589        -  When this flag is set, the buffer has been dequeued successfully,
 590           although the data might have been corrupted. This is recoverable,
 591           streaming may continue as normal and the buffer may be reused
 592           normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is
 593           called.
 594
 595     -  .. _`V4L2-BUF-FLAG-KEYFRAME`:
 596
 597        -  ``V4L2_BUF_FLAG_KEYFRAME``
 598
 599        -  0x00000008
 600
 601        -  Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
 602           ioctl. It may be set by video capture devices when the buffer
 603           contains a compressed image which is a key frame (or field), i. e.
 604           can be decompressed on its own. Also known as an I-frame.
 605           Applications can set this bit when ``type`` refers to an output
 606           stream.
 607
 608     -  .. _`V4L2-BUF-FLAG-PFRAME`:
 609
 610        -  ``V4L2_BUF_FLAG_PFRAME``
 611
 612        -  0x00000010
 613
 614        -  Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
 615           or fields which contain only differences to a previous key frame.
 616           Applications can set this bit when ``type`` refers to an output
 617           stream.
 618
 619     -  .. _`V4L2-BUF-FLAG-BFRAME`:
 620
 621        -  ``V4L2_BUF_FLAG_BFRAME``
 622
 623        -  0x00000020
 624
 625        -  Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
 626           predicted frame or field which contains only the differences
 627           between the current frame and both the preceding and following key
 628           frames to specify its content. Applications can set this bit when
 629           ``type`` refers to an output stream.
 630
 631     -  .. _`V4L2-BUF-FLAG-TIMECODE`:
 632
 633        -  ``V4L2_BUF_FLAG_TIMECODE``
 634
 635        -  0x00000100
 636
 637        -  The ``timecode`` field is valid. Drivers set or clear this flag
 638           when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set
 639           this bit and the corresponding ``timecode`` structure when
 640           ``type`` refers to an output stream.
 641
 642     -  .. _`V4L2-BUF-FLAG-PREPARED`:
 643
 644        -  ``V4L2_BUF_FLAG_PREPARED``
 645
 646        -  0x00000400
 647
 648        -  The buffer has been prepared for I/O and can be queued by the
 649           application. Drivers set or clear this flag when the
 650           :ref:`VIDIOC_QUERYBUF`,
 651           :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`,
 652           :ref:`VIDIOC_QBUF` or
 653           :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called.
 654
 655     -  .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`:
 656
 657        -  ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
 658
 659        -  0x00000800
 660
 661        -  Caches do not have to be invalidated for this buffer. Typically
 662           applications shall use this flag if the data captured in the
 663           buffer is not going to be touched by the CPU, instead the buffer
 664           will, probably, be passed on to a DMA-capable hardware unit for
 665           further processing or output.
 666
 667     -  .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`:
 668
 669        -  ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
 670
 671        -  0x00001000
 672
 673        -  Caches do not have to be cleaned for this buffer. Typically
 674           applications shall use this flag for output buffers if the data in
 675           this buffer has not been created by the CPU but by some
 676           DMA-capable unit, in which case caches have not been used.
 677
 678     -  .. _`V4L2-BUF-FLAG-LAST`:
 679
 680        -  ``V4L2_BUF_FLAG_LAST``
 681
 682        -  0x00100000
 683
 684        -  Last buffer produced by the hardware. mem2mem codec drivers set
 685           this flag on the capture queue for the last buffer when the
 686           :ref:`VIDIOC_QUERYBUF` or
 687           :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to
 688           hardware limitations, the last buffer may be empty. In this case
 689           the driver will set the ``bytesused`` field to 0, regardless of
 690           the format. Any Any subsequent call to the
 691           :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
 692           but return an ``EPIPE`` error code.
 693
 694     -  .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`:
 695
 696        -  ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
 697
 698        -  0x0000e000
 699
 700        -  Mask for timestamp types below. To test the timestamp type, mask
 701           out bits not belonging to timestamp type by performing a logical
 702           and operation with buffer flags and timestamp mask.
 703
 704     -  .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`:
 705
 706        -  ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
 707
 708        -  0x00000000
 709
 710        -  Unknown timestamp type. This type is used by drivers before Linux
 711           3.9 and may be either monotonic (see below) or realtime (wall
 712           clock). Monotonic clock has been favoured in embedded systems
 713           whereas most of the drivers use the realtime clock. Either kinds
 714           of timestamps are available in user space via
 715           :c:func:`clock_gettime(2)` using clock IDs ``CLOCK_MONOTONIC``
 716           and ``CLOCK_REALTIME``, respectively.
 717
 718     -  .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`:
 719
 720        -  ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
 721
 722        -  0x00002000
 723
 724        -  The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
 725           clock. To access the same clock outside V4L2, use
 726           :c:func:`clock_gettime(2)`.
 727
 728     -  .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`:
 729
 730        -  ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
 731
 732        -  0x00004000
 733
 734        -  The CAPTURE buffer timestamp has been taken from the corresponding
 735           OUTPUT buffer. This flag applies only to mem2mem devices.
 736
 737     -  .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`:
 738
 739        -  ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
 740
 741        -  0x00070000
 742
 743        -  Mask for timestamp sources below. The timestamp source defines the
 744           point of time the timestamp is taken in relation to the frame.
 745           Logical 'and' operation between the ``flags`` field and
 746           ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the
 747           timestamp source. Applications must set the timestamp source when
 748           ``type`` refers to an output stream and
 749           ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set.
 750
 751     -  .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`:
 752
 753        -  ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
 754
 755        -  0x00000000
 756
 757        -  End Of Frame. The buffer timestamp has been taken when the last
 758           pixel of the frame has been received or the last pixel of the
 759           frame has been transmitted. In practice, software generated
 760           timestamps will typically be read from the clock a small amount of
 761           time after the last pixel has been received or transmitten,
 762           depending on the system and other activity in it.
 763
 764     -  .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`:
 765
 766        -  ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
 767
 768        -  0x00010000
 769
 770        -  Start Of Exposure. The buffer timestamp has been taken when the
 771           exposure of the frame has begun. This is only valid for the
 772           ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
 773
 774
 775
 776 .. _v4l2-memory:
 777
 778 enum v4l2_memory
 779 ================
 780
 781 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 782
 783 .. flat-table::
 784     :header-rows:  0
 785     :stub-columns: 0
 786     :widths:       3 1 4
 787
 788
 789     -  .. row 1
 790
 791        -  ``V4L2_MEMORY_MMAP``
 792
 793        -  1
 794
 795        -  The buffer is used for :ref:`memory mapping <mmap>` I/O.
 796
 797     -  .. row 2
 798
 799        -  ``V4L2_MEMORY_USERPTR``
 800
 801        -  2
 802
 803        -  The buffer is used for :ref:`user pointer <userp>` I/O.
 804
 805     -  .. row 3
 806
 807        -  ``V4L2_MEMORY_OVERLAY``
 808
 809        -  3
 810
 811        -  [to do]
 812
 813     -  .. row 4
 814
 815        -  ``V4L2_MEMORY_DMABUF``
 816
 817        -  4
 818
 819        -  The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
 820
 821
 822
 823 Timecodes
 824 =========
 825
 826 The struct :c:type:`v4l2_timecode` structure is designed to hold a
 827 :ref:`smpte12m` or similar timecode. (struct
 828 :c:type:`struct timeval` timestamps are stored in struct
 829 :c:type:`v4l2_buffer` field ``timestamp``.)
 830
 831
 832 .. c:type:: v4l2_timecode
 833
 834 struct v4l2_timecode
 835 --------------------
 836
 837 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 838
 839 .. flat-table::
 840     :header-rows:  0
 841     :stub-columns: 0
 842     :widths:       1 1 2
 843
 844
 845     -  .. row 1
 846
 847        -  __u32
 848
 849        -  ``type``
 850
 851        -  Frame rate the timecodes are based on, see :ref:`timecode-type`.
 852
 853     -  .. row 2
 854
 855        -  __u32
 856
 857        -  ``flags``
 858
 859        -  Timecode flags, see :ref:`timecode-flags`.
 860
 861     -  .. row 3
 862
 863        -  __u8
 864
 865        -  ``frames``
 866
 867        -  Frame count, 0 ... 23/24/29/49/59, depending on the type of
 868           timecode.
 869
 870     -  .. row 4
 871
 872        -  __u8
 873
 874        -  ``seconds``
 875
 876        -  Seconds count, 0 ... 59. This is a binary, not BCD number.
 877
 878     -  .. row 5
 879
 880        -  __u8
 881
 882        -  ``minutes``
 883
 884        -  Minutes count, 0 ... 59. This is a binary, not BCD number.
 885
 886     -  .. row 6
 887
 888        -  __u8
 889
 890        -  ``hours``
 891
 892        -  Hours count, 0 ... 29. This is a binary, not BCD number.
 893
 894     -  .. row 7
 895
 896        -  __u8
 897
 898        -  ``userbits``\ [4]
 899
 900        -  The "user group" bits from the timecode.
 901
 902
 903
 904 .. _timecode-type:
 905
 906 Timecode Types
 907 --------------
 908
 909 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 910
 911 .. flat-table::
 912     :header-rows:  0
 913     :stub-columns: 0
 914     :widths:       3 1 4
 915
 916
 917     -  .. row 1
 918
 919        -  ``V4L2_TC_TYPE_24FPS``
 920
 921        -  1
 922
 923        -  24 frames per second, i. e. film.
 924
 925     -  .. row 2
 926
 927        -  ``V4L2_TC_TYPE_25FPS``
 928
 929        -  2
 930
 931        -  25 frames per second, i. e. PAL or SECAM video.
 932
 933     -  .. row 3
 934
 935        -  ``V4L2_TC_TYPE_30FPS``
 936
 937        -  3
 938
 939        -  30 frames per second, i. e. NTSC video.
 940
 941     -  .. row 4
 942
 943        -  ``V4L2_TC_TYPE_50FPS``
 944
 945        -  4
 946
 947        -
 948
 949     -  .. row 5
 950
 951        -  ``V4L2_TC_TYPE_60FPS``
 952
 953        -  5
 954
 955        -
 956
 957
 958
 959 .. _timecode-flags:
 960
 961 Timecode Flags
 962 --------------
 963
 964 .. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}|
 965
 966 .. flat-table::
 967     :header-rows:  0
 968     :stub-columns: 0
 969     :widths:       3 1 4
 970
 971
 972     -  .. row 1
 973
 974        -  ``V4L2_TC_FLAG_DROPFRAME``
 975
 976        -  0x0001
 977
 978        -  Indicates "drop frame" semantics for counting frames in 29.97 fps
 979           material. When set, frame numbers 0 and 1 at the start of each
 980           minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
 981           count.
 982
 983     -  .. row 2
 984
 985        -  ``V4L2_TC_FLAG_COLORFRAME``
 986
 987        -  0x0002
 988
 989        -  The "color frame" flag.
 990
 991     -  .. row 3
 992
 993        -  ``V4L2_TC_USERBITS_field``
 994
 995        -  0x000C
 996
 997        -  Field mask for the "binary group flags".
 998
 999     -  .. row 4
1000
1001        -  ``V4L2_TC_USERBITS_USERDEFINED``
1002
1003        -  0x0000
1004
1005        -  Unspecified format.
1006
1007     -  .. row 5
1008
1009        -  ``V4L2_TC_USERBITS_8BITCHARS``
1010
1011        -  0x0008
1012
1013        -  8-bit ISO characters.