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     * - __u32
  52       - ``index``
  53       -
  54       - Number of the buffer, set by the application except when calling
  55         :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the
  56         driver. This field can range from zero to the number of buffers
  57         allocated with the :ref:`VIDIOC_REQBUFS` ioctl
  58         (struct :c:type:`v4l2_requestbuffers`
  59         ``count``), plus any buffers allocated with
  60         :ref:`VIDIOC_CREATE_BUFS` minus one.
  61     * - __u32
  62       - ``type``
  63       -
  64       - Type of the buffer, same as struct
  65         :c:type:`v4l2_format` ``type`` or struct
  66         :c:type:`v4l2_requestbuffers` ``type``, set
  67         by the application. See :c:type:`v4l2_buf_type`
  68     * - __u32
  69       - ``bytesused``
  70       -
  71       - The number of bytes occupied by the data in the buffer. It depends
  72         on the negotiated data format and may change with each buffer for
  73         compressed variable size data like JPEG images. Drivers must set
  74         this field when ``type`` refers to a capture stream, applications
  75         when it refers to an output stream. If the application sets this
  76         to 0 for an output stream, then ``bytesused`` will be set to the
  77         size of the buffer (see the ``length`` field of this struct) by
  78         the driver. For multiplanar formats this field is ignored and the
  79         ``planes`` pointer is used instead.
  80     * - __u32
  81       - ``flags``
  82       -
  83       - Flags set by the application or driver, see :ref:`buffer-flags`.
  84     * - __u32
  85       - ``field``
  86       -
  87       - Indicates the field order of the image in the buffer, see
  88         :c:type:`v4l2_field`. This field is not used when the buffer
  89         contains VBI data. Drivers must set it when ``type`` refers to a
  90         capture stream, applications when it refers to an output stream.
  91     * - struct timeval
  92       - ``timestamp``
  93       -
  94       - For capture streams this is time when the first data byte was
  95         captured, as returned by the :c:func:`clock_gettime()` function
  96         for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in
  97         :ref:`buffer-flags`. For output streams the driver stores the
  98         time at which the last data byte was actually sent out in the
  99         ``timestamp`` field. This permits applications to monitor the
 100         drift between the video and system clock. For output streams that
 101         use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill
 102         in the timestamp which will be copied by the driver to the capture
 103         stream.
 104     * - struct :c:type:`v4l2_timecode`
 105       - ``timecode``
 106       -
 107       - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the
 108         ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
 109         structure contains a frame timecode. In
 110         :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and
 111         bottom field contain the same timecode. Timecodes are intended to
 112         help video editing and are typically recorded on video tapes, but
 113         also embedded in compressed formats like MPEG. This field is
 114         independent of the ``timestamp`` and ``sequence`` fields.
 115     * - __u32
 116       - ``sequence``
 117       -
 118       - Set by the driver, counting the frames (not fields!) in sequence.
 119         This field is set for both input and output devices.
 120     * - :cspan:`3`
 121
 122         In :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and
 123         bottom field have the same sequence number. The count starts at
 124         zero and includes dropped or repeated frames. A dropped frame was
 125         received by an input device but could not be stored due to lack of
 126         free buffer space. A repeated frame was displayed again by an
 127         output device because the application did not pass new data in
 128         time.
 129
 130         .. note::
 131
 132            This may count the frames received e.g. over USB, without
 133            taking into account the frames dropped by the remote hardware due
 134            to limited compression throughput or bus bandwidth. These devices
 135            identify by not enumerating any video standards, see
 136            :ref:`standard`.
 137
 138     * - __u32
 139       - ``memory``
 140       -
 141       - This field must be set by applications and/or drivers in
 142         accordance with the selected I/O method. See :c:type:`v4l2_memory`
 143     * - union
 144       - ``m``
 145     * -
 146       - __u32
 147       - ``offset``
 148       - For the single-planar API and when ``memory`` is
 149         ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
 150         start of the device memory. The value is returned by the driver
 151         and apart of serving as parameter to the
 152         :ref:`mmap() <func-mmap>` function not useful for applications.
 153         See :ref:`mmap` for details
 154     * -
 155       - unsigned long
 156       - ``userptr``
 157       - For the single-planar API and when ``memory`` is
 158         ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
 159         unsigned long type) in virtual memory, set by the application. See
 160         :ref:`userp` for details.
 161     * -
 162       - struct v4l2_plane
 163       - ``*planes``
 164       - When using the multi-planar API, contains a userspace pointer to
 165         an array of struct :c:type:`v4l2_plane`. The size of
 166         the array should be put in the ``length`` field of this
 167         struct :c:type:`v4l2_buffer` structure.
 168     * -
 169       - int
 170       - ``fd``
 171       - For the single-plane API and when ``memory`` is
 172         ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with
 173         a DMABUF buffer.
 174     * - __u32
 175       - ``length``
 176       -
 177       - Size of the buffer (not the payload) in bytes for the
 178         single-planar API. This is set by the driver based on the calls to
 179         :ref:`VIDIOC_REQBUFS` and/or
 180         :ref:`VIDIOC_CREATE_BUFS`. For the
 181         multi-planar API the application sets this to the number of
 182         elements in the ``planes`` array. The driver will fill in the
 183         actual number of valid elements in that array.
 184     * - __u32
 185       - ``reserved2``
 186       -
 187       - A place holder for future extensions. Drivers and applications
 188         must set this to 0.
 189     * - __u32
 190       - ``reserved``
 191       -
 192       - A place holder for future extensions. Drivers and applications
 193         must set this to 0.
 194
 195
 196
 197 .. c:type:: v4l2_plane
 198
 199 struct v4l2_plane
 200 =================
 201
 202 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
 203
 204 .. cssclass:: longtable
 205
 206 .. flat-table::
 207     :header-rows:  0
 208     :stub-columns: 0
 209     :widths:       1 1 1 2
 210
 211     * - __u32
 212       - ``bytesused``
 213       -
 214       - The number of bytes occupied by data in the plane (its payload).
 215         Drivers must set this field when ``type`` refers to a capture
 216         stream, applications when it refers to an output stream. If the
 217         application sets this to 0 for an output stream, then
 218         ``bytesused`` will be set to the size of the plane (see the
 219         ``length`` field of this struct) by the driver.
 220
 221         .. note::
 222
 223            Note that the actual image data starts at ``data_offset``
 224            which may not be 0.
 225     * - __u32
 226       - ``length``
 227       -
 228       - Size in bytes of the plane (not its payload). This is set by the
 229         driver based on the calls to
 230         :ref:`VIDIOC_REQBUFS` and/or
 231         :ref:`VIDIOC_CREATE_BUFS`.
 232     * - union
 233       - ``m``
 234       -
 235       -
 236     * -
 237       - __u32
 238       - ``mem_offset``
 239       - When the memory type in the containing struct
 240         :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this
 241         is the value that should be passed to :ref:`mmap() <func-mmap>`,
 242         similar to the ``offset`` field in struct
 243         :c:type:`v4l2_buffer`.
 244     * -
 245       - unsigned long
 246       - ``userptr``
 247       - When the memory type in the containing struct
 248         :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``,
 249         this is a userspace pointer to the memory allocated for this plane
 250         by an application.
 251     * -
 252       - int
 253       - ``fd``
 254       - When the memory type in the containing struct
 255         :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``,
 256         this is a file descriptor associated with a DMABUF buffer, similar
 257         to the ``fd`` field in struct :c:type:`v4l2_buffer`.
 258     * - __u32
 259       - ``data_offset``
 260       -
 261       - Offset in bytes to video data in the plane. Drivers must set this
 262         field when ``type`` refers to a capture stream, applications when
 263         it refers to an output stream.
 264
 265         .. note::
 266
 267            That data_offset is included  in ``bytesused``. So the
 268            size of the image in the plane is ``bytesused``-``data_offset``
 269            at offset ``data_offset`` from the start of the plane.
 270     * - __u32
 271       - ``reserved[11]``
 272       -
 273       - Reserved for future use. Should be zeroed by drivers and
 274         applications.
 275
 276
 277
 278 .. c:type:: v4l2_buf_type
 279
 280 enum v4l2_buf_type
 281 ==================
 282
 283 .. cssclass:: longtable
 284
 285 .. tabularcolumns:: |p{7.2cm}|p{0.6cm}|p{9.7cm}|
 286
 287 .. flat-table::
 288     :header-rows:  0
 289     :stub-columns: 0
 290     :widths:       4 1 9
 291
 292     * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
 293       - 1
 294       - Buffer of a single-planar video capture stream, see
 295         :ref:`capture`.
 296     * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
 297       - 9
 298       - Buffer of a multi-planar video capture stream, see
 299         :ref:`capture`.
 300     * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
 301       - 2
 302       - Buffer of a single-planar video output stream, see
 303         :ref:`output`.
 304     * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
 305       - 10
 306       - Buffer of a multi-planar video output stream, see :ref:`output`.
 307     * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
 308       - 3
 309       - Buffer for video overlay, see :ref:`overlay`.
 310     * - ``V4L2_BUF_TYPE_VBI_CAPTURE``
 311       - 4
 312       - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
 313     * - ``V4L2_BUF_TYPE_VBI_OUTPUT``
 314       - 5
 315       - Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
 316     * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
 317       - 6
 318       - Buffer of a sliced VBI capture stream, see :ref:`sliced`.
 319     * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
 320       - 7
 321       - Buffer of a sliced VBI output stream, see :ref:`sliced`.
 322     * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
 323       - 8
 324       - Buffer for video output overlay (OSD), see :ref:`osd`.
 325     * - ``V4L2_BUF_TYPE_SDR_CAPTURE``
 326       - 11
 327       - Buffer for Software Defined Radio (SDR) capture stream, see
 328         :ref:`sdr`.
 329     * - ``V4L2_BUF_TYPE_SDR_OUTPUT``
 330       - 12
 331       - Buffer for Software Defined Radio (SDR) output stream, see
 332         :ref:`sdr`.
 333
 334
 335
 336 .. _buffer-flags:
 337
 338 Buffer Flags
 339 ============
 340
 341 .. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}|
 342
 343 .. cssclass:: longtable
 344
 345 .. flat-table::
 346     :header-rows:  0
 347     :stub-columns: 0
 348     :widths:       3 1 4
 349
 350     * .. _`V4L2-BUF-FLAG-MAPPED`:
 351
 352       - ``V4L2_BUF_FLAG_MAPPED``
 353       - 0x00000001
 354       - The buffer resides in device memory and has been mapped into the
 355         application's address space, see :ref:`mmap` for details.
 356         Drivers set or clear this flag when the
 357         :ref:`VIDIOC_QUERYBUF`,
 358         :ref:`VIDIOC_QBUF` or
 359         :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the
 360         driver.
 361     * .. _`V4L2-BUF-FLAG-QUEUED`:
 362
 363       - ``V4L2_BUF_FLAG_QUEUED``
 364       - 0x00000002
 365       - Internally drivers maintain two buffer queues, an incoming and
 366         outgoing queue. When this flag is set, the buffer is currently on
 367         the incoming queue. It automatically moves to the outgoing queue
 368         after the buffer has been filled (capture devices) or displayed
 369         (output devices). Drivers set or clear this flag when the
 370         ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling
 371         the ``VIDIOC_QBUF``\ ioctl it is always set and after
 372         ``VIDIOC_DQBUF`` always cleared.
 373     * .. _`V4L2-BUF-FLAG-DONE`:
 374
 375       - ``V4L2_BUF_FLAG_DONE``
 376       - 0x00000004
 377       - When this flag is set, the buffer is currently on the outgoing
 378         queue, ready to be dequeued from the driver. Drivers set or clear
 379         this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After
 380         calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always
 381         cleared. Of course a buffer cannot be on both queues at the same
 382         time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag
 383         are mutually exclusive. They can be both cleared however, then the
 384         buffer is in "dequeued" state, in the application domain so to
 385         say.
 386     * .. _`V4L2-BUF-FLAG-ERROR`:
 387
 388       - ``V4L2_BUF_FLAG_ERROR``
 389       - 0x00000040
 390       - When this flag is set, the buffer has been dequeued successfully,
 391         although the data might have been corrupted. This is recoverable,
 392         streaming may continue as normal and the buffer may be reused
 393         normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is
 394         called.
 395     * .. _`V4L2-BUF-FLAG-KEYFRAME`:
 396
 397       - ``V4L2_BUF_FLAG_KEYFRAME``
 398       - 0x00000008
 399       - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
 400         ioctl. It may be set by video capture devices when the buffer
 401         contains a compressed image which is a key frame (or field), i. e.
 402         can be decompressed on its own. Also known as an I-frame.
 403         Applications can set this bit when ``type`` refers to an output
 404         stream.
 405     * .. _`V4L2-BUF-FLAG-PFRAME`:
 406
 407       - ``V4L2_BUF_FLAG_PFRAME``
 408       - 0x00000010
 409       - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
 410         or fields which contain only differences to a previous key frame.
 411         Applications can set this bit when ``type`` refers to an output
 412         stream.
 413     * .. _`V4L2-BUF-FLAG-BFRAME`:
 414
 415       - ``V4L2_BUF_FLAG_BFRAME``
 416       - 0x00000020
 417       - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
 418         predicted frame or field which contains only the differences
 419         between the current frame and both the preceding and following key
 420         frames to specify its content. Applications can set this bit when
 421         ``type`` refers to an output stream.
 422     * .. _`V4L2-BUF-FLAG-TIMECODE`:
 423
 424       - ``V4L2_BUF_FLAG_TIMECODE``
 425       - 0x00000100
 426       - The ``timecode`` field is valid. Drivers set or clear this flag
 427         when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set
 428         this bit and the corresponding ``timecode`` structure when
 429         ``type`` refers to an output stream.
 430     * .. _`V4L2-BUF-FLAG-PREPARED`:
 431
 432       - ``V4L2_BUF_FLAG_PREPARED``
 433       - 0x00000400
 434       - The buffer has been prepared for I/O and can be queued by the
 435         application. Drivers set or clear this flag when the
 436         :ref:`VIDIOC_QUERYBUF`,
 437         :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`,
 438         :ref:`VIDIOC_QBUF` or
 439         :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called.
 440     * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`:
 441
 442       - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
 443       - 0x00000800
 444       - Caches do not have to be invalidated for this buffer. Typically
 445         applications shall use this flag if the data captured in the
 446         buffer is not going to be touched by the CPU, instead the buffer
 447         will, probably, be passed on to a DMA-capable hardware unit for
 448         further processing or output.
 449     * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`:
 450
 451       - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
 452       - 0x00001000
 453       - Caches do not have to be cleaned for this buffer. Typically
 454         applications shall use this flag for output buffers if the data in
 455         this buffer has not been created by the CPU but by some
 456         DMA-capable unit, in which case caches have not been used.
 457     * .. _`V4L2-BUF-FLAG-LAST`:
 458
 459       - ``V4L2_BUF_FLAG_LAST``
 460       - 0x00100000
 461       - Last buffer produced by the hardware. mem2mem codec drivers set
 462         this flag on the capture queue for the last buffer when the
 463         :ref:`VIDIOC_QUERYBUF` or
 464         :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to
 465         hardware limitations, the last buffer may be empty. In this case
 466         the driver will set the ``bytesused`` field to 0, regardless of
 467         the format. Any Any subsequent call to the
 468         :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
 469         but return an ``EPIPE`` error code.
 470     * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`:
 471
 472       - ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
 473       - 0x0000e000
 474       - Mask for timestamp types below. To test the timestamp type, mask
 475         out bits not belonging to timestamp type by performing a logical
 476         and operation with buffer flags and timestamp mask.
 477     * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`:
 478
 479       - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
 480       - 0x00000000
 481       - Unknown timestamp type. This type is used by drivers before Linux
 482         3.9 and may be either monotonic (see below) or realtime (wall
 483         clock). Monotonic clock has been favoured in embedded systems
 484         whereas most of the drivers use the realtime clock. Either kinds
 485         of timestamps are available in user space via
 486         :c:func:`clock_gettime` using clock IDs ``CLOCK_MONOTONIC``
 487         and ``CLOCK_REALTIME``, respectively.
 488     * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`:
 489
 490       - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
 491       - 0x00002000
 492       - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
 493         clock. To access the same clock outside V4L2, use
 494         :c:func:`clock_gettime`.
 495     * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`:
 496
 497       - ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
 498       - 0x00004000
 499       - The CAPTURE buffer timestamp has been taken from the corresponding
 500         OUTPUT buffer. This flag applies only to mem2mem devices.
 501     * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`:
 502
 503       - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
 504       - 0x00070000
 505       - Mask for timestamp sources below. The timestamp source defines the
 506         point of time the timestamp is taken in relation to the frame.
 507         Logical 'and' operation between the ``flags`` field and
 508         ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the
 509         timestamp source. Applications must set the timestamp source when
 510         ``type`` refers to an output stream and
 511         ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set.
 512     * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`:
 513
 514       - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
 515       - 0x00000000
 516       - End Of Frame. The buffer timestamp has been taken when the last
 517         pixel of the frame has been received or the last pixel of the
 518         frame has been transmitted. In practice, software generated
 519         timestamps will typically be read from the clock a small amount of
 520         time after the last pixel has been received or transmitten,
 521         depending on the system and other activity in it.
 522     * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`:
 523
 524       - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
 525       - 0x00010000
 526       - Start Of Exposure. The buffer timestamp has been taken when the
 527         exposure of the frame has begun. This is only valid for the
 528         ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
 529
 530
 531
 532 .. c:type:: v4l2_memory
 533
 534 enum v4l2_memory
 535 ================
 536
 537 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 538
 539 .. flat-table::
 540     :header-rows:  0
 541     :stub-columns: 0
 542     :widths:       3 1 4
 543
 544     * - ``V4L2_MEMORY_MMAP``
 545       - 1
 546       - The buffer is used for :ref:`memory mapping <mmap>` I/O.
 547     * - ``V4L2_MEMORY_USERPTR``
 548       - 2
 549       - The buffer is used for :ref:`user pointer <userp>` I/O.
 550     * - ``V4L2_MEMORY_OVERLAY``
 551       - 3
 552       - [to do]
 553     * - ``V4L2_MEMORY_DMABUF``
 554       - 4
 555       - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
 556
 557
 558
 559 Timecodes
 560 =========
 561
 562 The struct :c:type:`v4l2_timecode` structure is designed to hold a
 563 :ref:`smpte12m` or similar timecode. (struct
 564 struct :c:type:`timeval` timestamps are stored in struct
 565 :c:type:`v4l2_buffer` field ``timestamp``.)
 566
 567
 568 .. c:type:: v4l2_timecode
 569
 570 struct v4l2_timecode
 571 --------------------
 572
 573 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 574
 575 .. flat-table::
 576     :header-rows:  0
 577     :stub-columns: 0
 578     :widths:       1 1 2
 579
 580     * - __u32
 581       - ``type``
 582       - Frame rate the timecodes are based on, see :ref:`timecode-type`.
 583     * - __u32
 584       - ``flags``
 585       - Timecode flags, see :ref:`timecode-flags`.
 586     * - __u8
 587       - ``frames``
 588       - Frame count, 0 ... 23/24/29/49/59, depending on the type of
 589         timecode.
 590     * - __u8
 591       - ``seconds``
 592       - Seconds count, 0 ... 59. This is a binary, not BCD number.
 593     * - __u8
 594       - ``minutes``
 595       - Minutes count, 0 ... 59. This is a binary, not BCD number.
 596     * - __u8
 597       - ``hours``
 598       - Hours count, 0 ... 29. This is a binary, not BCD number.
 599     * - __u8
 600       - ``userbits``\ [4]
 601       - The "user group" bits from the timecode.
 602
 603
 604
 605 .. _timecode-type:
 606
 607 Timecode Types
 608 --------------
 609
 610 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 611
 612 .. flat-table::
 613     :header-rows:  0
 614     :stub-columns: 0
 615     :widths:       3 1 4
 616
 617     * - ``V4L2_TC_TYPE_24FPS``
 618       - 1
 619       - 24 frames per second, i. e. film.
 620     * - ``V4L2_TC_TYPE_25FPS``
 621       - 2
 622       - 25 frames per second, i. e. PAL or SECAM video.
 623     * - ``V4L2_TC_TYPE_30FPS``
 624       - 3
 625       - 30 frames per second, i. e. NTSC video.
 626     * - ``V4L2_TC_TYPE_50FPS``
 627       - 4
 628       -
 629     * - ``V4L2_TC_TYPE_60FPS``
 630       - 5
 631       -
 632
 633
 634
 635 .. _timecode-flags:
 636
 637 Timecode Flags
 638 --------------
 639
 640 .. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}|
 641
 642 .. flat-table::
 643     :header-rows:  0
 644     :stub-columns: 0
 645     :widths:       3 1 4
 646
 647     * - ``V4L2_TC_FLAG_DROPFRAME``
 648       - 0x0001
 649       - Indicates "drop frame" semantics for counting frames in 29.97 fps
 650         material. When set, frame numbers 0 and 1 at the start of each
 651         minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
 652         count.
 653     * - ``V4L2_TC_FLAG_COLORFRAME``
 654       - 0x0002
 655       - The "color frame" flag.
 656     * - ``V4L2_TC_USERBITS_field``
 657       - 0x000C
 658       - Field mask for the "binary group flags".
 659     * - ``V4L2_TC_USERBITS_USERDEFINED``
 660       - 0x0000
 661       - Unspecified format.
 662     * - ``V4L2_TC_USERBITS_8BITCHARS``
 663       - 0x0008
 664       - 8-bit ISO characters.