1 .. -*- coding: utf-8; mode: rst -*-
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.
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
37 Interactions between formats, controls and buffers
38 ==================================================
40 V4L2 exposes parameters that influence the buffer size, or the way data is
41 laid out in the buffer. Those parameters are exposed through both formats and
42 controls. One example of such a control is the ``V4L2_CID_ROTATE`` control
43 that modifies the direction in which pixels are stored in the buffer, as well
44 as the buffer size when the selected format includes padding at the end of
47 The set of information needed to interpret the content of a buffer (e.g. the
48 pixel format, the line stride, the tiling orientation or the rotation) is
49 collectively referred to in the rest of this section as the buffer layout.
51 Modifying formats or controls that influence the buffer size or layout require
52 the stream to be stopped. Any attempt at such a modification while the stream
53 is active shall cause the ioctl setting the format or the control to return
54 the ``EBUSY`` error code.
58 The :c:func:`VIDIOC_S_SELECTION` ioctl can, depending on the hardware (for
59 instance if the device doesn't include a scaler), modify the format in
60 addition to the selection rectangle. Similarly, the
61 :c:func:`VIDIOC_S_INPUT`, :c:func:`VIDIOC_S_OUTPUT`, :c:func:`VIDIOC_S_STD`
62 and :c:func:`VIDIOC_S_DV_TIMINGS` ioctls can also modify the format and
63 selection rectangles. When those ioctls result in a buffer size or layout
64 change, drivers shall handle that condition as they would handle it in the
65 :c:func:`VIDIOC_S_FMT` ioctl in all cases described in this section.
67 Controls that only influence the buffer layout can be modified at any time
68 when the stream is stopped. As they don't influence the buffer size, no
69 special handling is needed to synchronize those controls with buffer
72 Formats and controls that influence the buffer size interact with buffer
73 allocation. The simplest way to handle this is for drivers to always require
74 buffers to be reallocated in order to change those formats or controls. In
75 that case, to perform such changes, userspace applications shall first stop
76 the video stream with the :c:func:`VIDIOC_STREAMOFF` ioctl if it is running
77 and free all buffers with the :c:func:`VIDIOC_REQBUFS` ioctl if they are
78 allocated. The format or controls can then be modified, and buffers shall then
79 be reallocated and the stream restarted. A typical ioctl sequence is
89 The second :c:func:`VIDIOC_REQBUFS` call will take the new format and control
90 value into account to compute the buffer size to allocate. Applications can
91 also retrieve the size by calling the :c:func:`VIDIOC_G_FMT` ioctl if needed.
95 The API doesn't mandate the above order for control (3.) and format (4.)
96 changes. Format and controls can be set in a different order, or even
97 interleaved, depending on the device and use case. For instance some
98 controls might behave differently for different pixel formats, in which
99 case the format might need to be set first.
101 When reallocation is required, any attempt to modify format or controls that
102 influences the buffer size while buffers are allocated shall cause the format
103 or control set ioctl to return the ``EBUSY`` error. Any attempt to queue a
104 buffer too small for the current format or controls shall cause the
105 :c:func:`VIDIOC_QBUF` ioctl to return a ``EINVAL`` error.
107 Buffer reallocation is an expensive operation. To avoid that cost, drivers can
108 (and are encouraged to) allow format or controls that influence the buffer
109 size to be changed with buffers allocated. In that case, a typical ioctl
110 sequence to modify format and controls is
113 #. VIDIOC_S_EXT_CTRLS
118 For this sequence to operate correctly, queued buffers need to be large enough
119 for the new format or controls. Drivers shall return a ``ENOSPC`` error in
120 response to format change (:c:func:`VIDIOC_S_FMT`) or control changes
121 (:c:func:`VIDIOC_S_CTRL` or :c:func:`VIDIOC_S_EXT_CTRLS`) if buffers too small
122 for the new format are currently queued. As a simplification, drivers are
123 allowed to return a ``EBUSY`` error from these ioctls if any buffer is
124 currently queued, without checking the queued buffers sizes.
126 Additionally, drivers shall return a ``EINVAL`` error from the
127 :c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the
128 current format or controls. Together, these requirements ensure that queued
129 buffers will always be large enough for the configured format and controls.
131 Userspace applications can query the buffer size required for a given format
132 and controls by first setting the desired control values and then trying the
133 desired format. The :c:func:`VIDIOC_TRY_FMT` ioctl will return the required
136 #. VIDIOC_S_EXT_CTRLS(x)
138 #. VIDIOC_S_EXT_CTRLS(y)
141 The :c:func:`VIDIOC_CREATE_BUFS` ioctl can then be used to allocate buffers
142 based on the queried sizes (for instance by allocating a set of buffers large
143 enough for all the desired formats and controls, or by allocating separate set
144 of appropriately sized buffers for each use case).
147 .. c:type:: v4l2_buffer
152 .. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.3cm}|p{10.5cm}|
154 .. cssclass:: longtable
156 .. flat-table:: struct v4l2_buffer
164 - Number of the buffer, set by the application except when calling
165 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the
166 driver. This field can range from zero to the number of buffers
167 allocated with the :ref:`VIDIOC_REQBUFS` ioctl
168 (struct :c:type:`v4l2_requestbuffers`
169 ``count``), plus any buffers allocated with
170 :ref:`VIDIOC_CREATE_BUFS` minus one.
174 - Type of the buffer, same as struct
175 :c:type:`v4l2_format` ``type`` or struct
176 :c:type:`v4l2_requestbuffers` ``type``, set
177 by the application. See :c:type:`v4l2_buf_type`
181 - The number of bytes occupied by the data in the buffer. It depends
182 on the negotiated data format and may change with each buffer for
183 compressed variable size data like JPEG images. Drivers must set
184 this field when ``type`` refers to a capture stream, applications
185 when it refers to an output stream. If the application sets this
186 to 0 for an output stream, then ``bytesused`` will be set to the
187 size of the buffer (see the ``length`` field of this struct) by
188 the driver. For multiplanar formats this field is ignored and the
189 ``planes`` pointer is used instead.
193 - Flags set by the application or driver, see :ref:`buffer-flags`.
197 - Indicates the field order of the image in the buffer, see
198 :c:type:`v4l2_field`. This field is not used when the buffer
199 contains VBI data. Drivers must set it when ``type`` refers to a
200 capture stream, applications when it refers to an output stream.
204 - For capture streams this is time when the first data byte was
205 captured, as returned by the :c:func:`clock_gettime()` function
206 for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in
207 :ref:`buffer-flags`. For output streams the driver stores the
208 time at which the last data byte was actually sent out in the
209 ``timestamp`` field. This permits applications to monitor the
210 drift between the video and system clock. For output streams that
211 use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill
212 in the timestamp which will be copied by the driver to the capture
214 * - struct :c:type:`v4l2_timecode`
217 - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the
218 ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
219 structure contains a frame timecode. In
220 :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and
221 bottom field contain the same timecode. Timecodes are intended to
222 help video editing and are typically recorded on video tapes, but
223 also embedded in compressed formats like MPEG. This field is
224 independent of the ``timestamp`` and ``sequence`` fields.
228 - Set by the driver, counting the frames (not fields!) in sequence.
229 This field is set for both input and output devices.
232 In :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and
233 bottom field have the same sequence number. The count starts at
234 zero and includes dropped or repeated frames. A dropped frame was
235 received by an input device but could not be stored due to lack of
236 free buffer space. A repeated frame was displayed again by an
237 output device because the application did not pass new data in
242 This may count the frames received e.g. over USB, without
243 taking into account the frames dropped by the remote hardware due
244 to limited compression throughput or bus bandwidth. These devices
245 identify by not enumerating any video standards, see
251 - This field must be set by applications and/or drivers in
252 accordance with the selected I/O method. See :c:type:`v4l2_memory`
258 - For the single-planar API and when ``memory`` is
259 ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
260 start of the device memory. The value is returned by the driver
261 and apart of serving as parameter to the
262 :ref:`mmap() <func-mmap>` function not useful for applications.
263 See :ref:`mmap` for details
267 - For the single-planar API and when ``memory`` is
268 ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
269 unsigned long type) in virtual memory, set by the application. See
270 :ref:`userp` for details.
274 - When using the multi-planar API, contains a userspace pointer to
275 an array of struct :c:type:`v4l2_plane`. The size of
276 the array should be put in the ``length`` field of this
277 struct :c:type:`v4l2_buffer` structure.
281 - For the single-plane API and when ``memory`` is
282 ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with
287 - Size of the buffer (not the payload) in bytes for the
288 single-planar API. This is set by the driver based on the calls to
289 :ref:`VIDIOC_REQBUFS` and/or
290 :ref:`VIDIOC_CREATE_BUFS`. For the
291 multi-planar API the application sets this to the number of
292 elements in the ``planes`` array. The driver will fill in the
293 actual number of valid elements in that array.
297 - A place holder for future extensions. Drivers and applications
302 - A place holder for future extensions. Drivers and applications
307 .. c:type:: v4l2_plane
312 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
314 .. cssclass:: longtable
324 - The number of bytes occupied by data in the plane (its payload).
325 Drivers must set this field when ``type`` refers to a capture
326 stream, applications when it refers to an output stream. If the
327 application sets this to 0 for an output stream, then
328 ``bytesused`` will be set to the size of the plane (see the
329 ``length`` field of this struct) by the driver.
333 Note that the actual image data starts at ``data_offset``
338 - Size in bytes of the plane (not its payload). This is set by the
339 driver based on the calls to
340 :ref:`VIDIOC_REQBUFS` and/or
341 :ref:`VIDIOC_CREATE_BUFS`.
349 - When the memory type in the containing struct
350 :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this
351 is the value that should be passed to :ref:`mmap() <func-mmap>`,
352 similar to the ``offset`` field in struct
353 :c:type:`v4l2_buffer`.
357 - When the memory type in the containing struct
358 :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``,
359 this is a userspace pointer to the memory allocated for this plane
364 - When the memory type in the containing struct
365 :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``,
366 this is a file descriptor associated with a DMABUF buffer, similar
367 to the ``fd`` field in struct :c:type:`v4l2_buffer`.
371 - Offset in bytes to video data in the plane. Drivers must set this
372 field when ``type`` refers to a capture stream, applications when
373 it refers to an output stream.
377 That data_offset is included in ``bytesused``. So the
378 size of the image in the plane is ``bytesused``-``data_offset``
379 at offset ``data_offset`` from the start of the plane.
383 - Reserved for future use. Should be zeroed by drivers and
388 .. c:type:: v4l2_buf_type
393 .. cssclass:: longtable
395 .. tabularcolumns:: |p{7.2cm}|p{0.6cm}|p{9.7cm}|
402 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
404 - Buffer of a single-planar video capture stream, see
406 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
408 - Buffer of a multi-planar video capture stream, see
410 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
412 - Buffer of a single-planar video output stream, see
414 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
416 - Buffer of a multi-planar video output stream, see :ref:`output`.
417 * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
419 - Buffer for video overlay, see :ref:`overlay`.
420 * - ``V4L2_BUF_TYPE_VBI_CAPTURE``
422 - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
423 * - ``V4L2_BUF_TYPE_VBI_OUTPUT``
425 - Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
426 * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
428 - Buffer of a sliced VBI capture stream, see :ref:`sliced`.
429 * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
431 - Buffer of a sliced VBI output stream, see :ref:`sliced`.
432 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
434 - Buffer for video output overlay (OSD), see :ref:`osd`.
435 * - ``V4L2_BUF_TYPE_SDR_CAPTURE``
437 - Buffer for Software Defined Radio (SDR) capture stream, see
439 * - ``V4L2_BUF_TYPE_SDR_OUTPUT``
441 - Buffer for Software Defined Radio (SDR) output stream, see
451 .. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}|
453 .. cssclass:: longtable
460 * .. _`V4L2-BUF-FLAG-MAPPED`:
462 - ``V4L2_BUF_FLAG_MAPPED``
464 - The buffer resides in device memory and has been mapped into the
465 application's address space, see :ref:`mmap` for details.
466 Drivers set or clear this flag when the
467 :ref:`VIDIOC_QUERYBUF`,
468 :ref:`VIDIOC_QBUF` or
469 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the
471 * .. _`V4L2-BUF-FLAG-QUEUED`:
473 - ``V4L2_BUF_FLAG_QUEUED``
475 - Internally drivers maintain two buffer queues, an incoming and
476 outgoing queue. When this flag is set, the buffer is currently on
477 the incoming queue. It automatically moves to the outgoing queue
478 after the buffer has been filled (capture devices) or displayed
479 (output devices). Drivers set or clear this flag when the
480 ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling
481 the ``VIDIOC_QBUF``\ ioctl it is always set and after
482 ``VIDIOC_DQBUF`` always cleared.
483 * .. _`V4L2-BUF-FLAG-DONE`:
485 - ``V4L2_BUF_FLAG_DONE``
487 - When this flag is set, the buffer is currently on the outgoing
488 queue, ready to be dequeued from the driver. Drivers set or clear
489 this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After
490 calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always
491 cleared. Of course a buffer cannot be on both queues at the same
492 time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag
493 are mutually exclusive. They can be both cleared however, then the
494 buffer is in "dequeued" state, in the application domain so to
496 * .. _`V4L2-BUF-FLAG-ERROR`:
498 - ``V4L2_BUF_FLAG_ERROR``
500 - When this flag is set, the buffer has been dequeued successfully,
501 although the data might have been corrupted. This is recoverable,
502 streaming may continue as normal and the buffer may be reused
503 normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is
505 * .. _`V4L2-BUF-FLAG-KEYFRAME`:
507 - ``V4L2_BUF_FLAG_KEYFRAME``
509 - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
510 ioctl. It may be set by video capture devices when the buffer
511 contains a compressed image which is a key frame (or field), i. e.
512 can be decompressed on its own. Also known as an I-frame.
513 Applications can set this bit when ``type`` refers to an output
515 * .. _`V4L2-BUF-FLAG-PFRAME`:
517 - ``V4L2_BUF_FLAG_PFRAME``
519 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
520 or fields which contain only differences to a previous key frame.
521 Applications can set this bit when ``type`` refers to an output
523 * .. _`V4L2-BUF-FLAG-BFRAME`:
525 - ``V4L2_BUF_FLAG_BFRAME``
527 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
528 predicted frame or field which contains only the differences
529 between the current frame and both the preceding and following key
530 frames to specify its content. Applications can set this bit when
531 ``type`` refers to an output stream.
532 * .. _`V4L2-BUF-FLAG-TIMECODE`:
534 - ``V4L2_BUF_FLAG_TIMECODE``
536 - The ``timecode`` field is valid. Drivers set or clear this flag
537 when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set
538 this bit and the corresponding ``timecode`` structure when
539 ``type`` refers to an output stream.
540 * .. _`V4L2-BUF-FLAG-PREPARED`:
542 - ``V4L2_BUF_FLAG_PREPARED``
544 - The buffer has been prepared for I/O and can be queued by the
545 application. Drivers set or clear this flag when the
546 :ref:`VIDIOC_QUERYBUF`,
547 :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`,
548 :ref:`VIDIOC_QBUF` or
549 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called.
550 * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`:
552 - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
554 - Caches do not have to be invalidated for this buffer. Typically
555 applications shall use this flag if the data captured in the
556 buffer is not going to be touched by the CPU, instead the buffer
557 will, probably, be passed on to a DMA-capable hardware unit for
558 further processing or output.
559 * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`:
561 - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
563 - Caches do not have to be cleaned for this buffer. Typically
564 applications shall use this flag for output buffers if the data in
565 this buffer has not been created by the CPU but by some
566 DMA-capable unit, in which case caches have not been used.
567 * .. _`V4L2-BUF-FLAG-LAST`:
569 - ``V4L2_BUF_FLAG_LAST``
571 - Last buffer produced by the hardware. mem2mem codec drivers set
572 this flag on the capture queue for the last buffer when the
573 :ref:`VIDIOC_QUERYBUF` or
574 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to
575 hardware limitations, the last buffer may be empty. In this case
576 the driver will set the ``bytesused`` field to 0, regardless of
577 the format. Any Any subsequent call to the
578 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
579 but return an ``EPIPE`` error code.
580 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`:
582 - ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
584 - Mask for timestamp types below. To test the timestamp type, mask
585 out bits not belonging to timestamp type by performing a logical
586 and operation with buffer flags and timestamp mask.
587 * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`:
589 - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
591 - Unknown timestamp type. This type is used by drivers before Linux
592 3.9 and may be either monotonic (see below) or realtime (wall
593 clock). Monotonic clock has been favoured in embedded systems
594 whereas most of the drivers use the realtime clock. Either kinds
595 of timestamps are available in user space via
596 :c:func:`clock_gettime` using clock IDs ``CLOCK_MONOTONIC``
597 and ``CLOCK_REALTIME``, respectively.
598 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`:
600 - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
602 - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
603 clock. To access the same clock outside V4L2, use
604 :c:func:`clock_gettime`.
605 * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`:
607 - ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
609 - The CAPTURE buffer timestamp has been taken from the corresponding
610 OUTPUT buffer. This flag applies only to mem2mem devices.
611 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`:
613 - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
615 - Mask for timestamp sources below. The timestamp source defines the
616 point of time the timestamp is taken in relation to the frame.
617 Logical 'and' operation between the ``flags`` field and
618 ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the
619 timestamp source. Applications must set the timestamp source when
620 ``type`` refers to an output stream and
621 ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set.
622 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`:
624 - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
626 - End Of Frame. The buffer timestamp has been taken when the last
627 pixel of the frame has been received or the last pixel of the
628 frame has been transmitted. In practice, software generated
629 timestamps will typically be read from the clock a small amount of
630 time after the last pixel has been received or transmitten,
631 depending on the system and other activity in it.
632 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`:
634 - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
636 - Start Of Exposure. The buffer timestamp has been taken when the
637 exposure of the frame has begun. This is only valid for the
638 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
642 .. c:type:: v4l2_memory
647 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
654 * - ``V4L2_MEMORY_MMAP``
656 - The buffer is used for :ref:`memory mapping <mmap>` I/O.
657 * - ``V4L2_MEMORY_USERPTR``
659 - The buffer is used for :ref:`user pointer <userp>` I/O.
660 * - ``V4L2_MEMORY_OVERLAY``
663 * - ``V4L2_MEMORY_DMABUF``
665 - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
672 The struct :c:type:`v4l2_timecode` structure is designed to hold a
673 :ref:`smpte12m` or similar timecode. (struct
674 struct :c:type:`timeval` timestamps are stored in struct
675 :c:type:`v4l2_buffer` field ``timestamp``.)
678 .. c:type:: v4l2_timecode
683 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
692 - Frame rate the timecodes are based on, see :ref:`timecode-type`.
695 - Timecode flags, see :ref:`timecode-flags`.
698 - Frame count, 0 ... 23/24/29/49/59, depending on the type of
702 - Seconds count, 0 ... 59. This is a binary, not BCD number.
705 - Minutes count, 0 ... 59. This is a binary, not BCD number.
708 - Hours count, 0 ... 29. This is a binary, not BCD number.
711 - The "user group" bits from the timecode.
720 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
727 * - ``V4L2_TC_TYPE_24FPS``
729 - 24 frames per second, i. e. film.
730 * - ``V4L2_TC_TYPE_25FPS``
732 - 25 frames per second, i. e. PAL or SECAM video.
733 * - ``V4L2_TC_TYPE_30FPS``
735 - 30 frames per second, i. e. NTSC video.
736 * - ``V4L2_TC_TYPE_50FPS``
739 * - ``V4L2_TC_TYPE_60FPS``
750 .. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}|
757 * - ``V4L2_TC_FLAG_DROPFRAME``
759 - Indicates "drop frame" semantics for counting frames in 29.97 fps
760 material. When set, frame numbers 0 and 1 at the start of each
761 minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
763 * - ``V4L2_TC_FLAG_COLORFRAME``
765 - The "color frame" flag.
766 * - ``V4L2_TC_USERBITS_field``
768 - Field mask for the "binary group flags".
769 * - ``V4L2_TC_USERBITS_USERDEFINED``
771 - Unspecified format.
772 * - ``V4L2_TC_USERBITS_8BITCHARS``
774 - 8-bit ISO characters.