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