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