diff options
Diffstat (limited to '')
| -rw-r--r-- | Documentation/userspace-api/media/v4l/buffer.rst | 841 |
1 files changed, 841 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst new file mode 100644 index 000000000..4638ec64d --- /dev/null +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -0,0 +1,841 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _buffer: + +******* +Buffers +******* + +A buffer contains data exchanged by application and driver using one of +the Streaming I/O methods. In the multi-planar API, the data is held in +planes, while the buffer structure acts as a container for the planes. +Only pointers to buffers (planes) are exchanged, the data itself is not +copied. These pointers, together with meta-information like timestamps +or field parity, are stored in a struct :c:type:`v4l2_buffer`, +argument to the :ref:`VIDIOC_QUERYBUF`, +:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API, +some plane-specific members of struct :c:type:`v4l2_buffer`, +such as pointers and sizes for each plane, are stored in +struct :c:type:`v4l2_plane` instead. In that case, +struct :c:type:`v4l2_buffer` contains an array of plane structures. + +Dequeued video buffers come with timestamps. The driver decides at which +part of the frame and with which clock the timestamp is taken. Please +see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and +``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags +are always valid and constant across all buffers during the whole video +stream. Changes in these flags may take place as a side effect of +:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or +:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The +``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on +mem-to-mem devices is an exception to the rule: the timestamp source +flags are copied from the OUTPUT video buffer to the CAPTURE video +buffer. + +Interactions between formats, controls and buffers +================================================== + +V4L2 exposes parameters that influence the buffer size, or the way data is +laid out in the buffer. Those parameters are exposed through both formats and +controls. One example of such a control is the ``V4L2_CID_ROTATE`` control +that modifies the direction in which pixels are stored in the buffer, as well +as the buffer size when the selected format includes padding at the end of +lines. + +The set of information needed to interpret the content of a buffer (e.g. the +pixel format, the line stride, the tiling orientation or the rotation) is +collectively referred to in the rest of this section as the buffer layout. + +Controls that can modify the buffer layout shall set the +``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag. + +Modifying formats or controls that influence the buffer size or layout require +the stream to be stopped. Any attempt at such a modification while the stream +is active shall cause the ioctl setting the format or the control to return +the ``EBUSY`` error code. In that case drivers shall also set the +``V4L2_CTRL_FLAG_GRABBED`` flag when calling +:c:func:`VIDIOC_QUERYCTRL` or :c:func:`VIDIOC_QUERY_EXT_CTRL` for such a +control while the stream is active. + +.. note:: + + The :c:func:`VIDIOC_S_SELECTION` ioctl can, depending on the hardware (for + instance if the device doesn't include a scaler), modify the format in + addition to the selection rectangle. Similarly, the + :c:func:`VIDIOC_S_INPUT`, :c:func:`VIDIOC_S_OUTPUT`, :c:func:`VIDIOC_S_STD` + and :c:func:`VIDIOC_S_DV_TIMINGS` ioctls can also modify the format and + selection rectangles. When those ioctls result in a buffer size or layout + change, drivers shall handle that condition as they would handle it in the + :c:func:`VIDIOC_S_FMT` ioctl in all cases described in this section. + +Controls that only influence the buffer layout can be modified at any time +when the stream is stopped. As they don't influence the buffer size, no +special handling is needed to synchronize those controls with buffer +allocation and the ``V4L2_CTRL_FLAG_GRABBED`` flag is cleared once the +stream is stopped. + +Formats and controls that influence the buffer size interact with buffer +allocation. The simplest way to handle this is for drivers to always require +buffers to be reallocated in order to change those formats or controls. In +that case, to perform such changes, userspace applications shall first stop +the video stream with the :c:func:`VIDIOC_STREAMOFF` ioctl if it is running +and free all buffers with the :c:func:`VIDIOC_REQBUFS` ioctl if they are +allocated. After freeing all buffers the ``V4L2_CTRL_FLAG_GRABBED`` flag +for controls is cleared. The format or controls can then be modified, and +buffers shall then be reallocated and the stream restarted. A typical ioctl +sequence is + + #. VIDIOC_STREAMOFF + #. VIDIOC_REQBUFS(0) + #. VIDIOC_S_EXT_CTRLS + #. VIDIOC_S_FMT + #. VIDIOC_REQBUFS(n) + #. VIDIOC_QBUF + #. VIDIOC_STREAMON + +The second :c:func:`VIDIOC_REQBUFS` call will take the new format and control +value into account to compute the buffer size to allocate. Applications can +also retrieve the size by calling the :c:func:`VIDIOC_G_FMT` ioctl if needed. + +.. note:: + + The API doesn't mandate the above order for control (3.) and format (4.) + changes. Format and controls can be set in a different order, or even + interleaved, depending on the device and use case. For instance some + controls might behave differently for different pixel formats, in which + case the format might need to be set first. + +When reallocation is required, any attempt to modify format or controls that +influences the buffer size while buffers are allocated shall cause the format +or control set ioctl to return the ``EBUSY`` error. Any attempt to queue a +buffer too small for the current format or controls shall cause the +:c:func:`VIDIOC_QBUF` ioctl to return a ``EINVAL`` error. + +Buffer reallocation is an expensive operation. To avoid that cost, drivers can +(and are encouraged to) allow format or controls that influence the buffer +size to be changed with buffers allocated. In that case, a typical ioctl +sequence to modify format and controls is + + #. VIDIOC_STREAMOFF + #. VIDIOC_S_EXT_CTRLS + #. VIDIOC_S_FMT + #. VIDIOC_QBUF + #. VIDIOC_STREAMON + +For this sequence to operate correctly, queued buffers need to be large enough +for the new format or controls. Drivers shall return a ``ENOSPC`` error in +response to format change (:c:func:`VIDIOC_S_FMT`) or control changes +(:c:func:`VIDIOC_S_CTRL` or :c:func:`VIDIOC_S_EXT_CTRLS`) if buffers too small +for the new format are currently queued. As a simplification, drivers are +allowed to return a ``EBUSY`` error from these ioctls if any buffer is +currently queued, without checking the queued buffers sizes. + +Additionally, drivers shall return a ``EINVAL`` error from the +:c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the +current format or controls. Together, these requirements ensure that queued +buffers will always be large enough for the configured format and controls. + +Userspace applications can query the buffer size required for a given format +and controls by first setting the desired control values and then trying the +desired format. The :c:func:`VIDIOC_TRY_FMT` ioctl will return the required +buffer size. + + #. VIDIOC_S_EXT_CTRLS(x) + #. VIDIOC_TRY_FMT() + #. VIDIOC_S_EXT_CTRLS(y) + #. VIDIOC_TRY_FMT() + +The :c:func:`VIDIOC_CREATE_BUFS` ioctl can then be used to allocate buffers +based on the queried sizes (for instance by allocating a set of buffers large +enough for all the desired formats and controls, or by allocating separate set +of appropriately sized buffers for each use case). + +.. c:type:: v4l2_buffer + +struct v4l2_buffer +================== + +.. tabularcolumns:: |p{2.9cm}|p{2.4cm}|p{12.0cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_buffer + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 10 + + * - __u32 + - ``index`` + - Number of the buffer, set by the application except when calling + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the + driver. This field can range from zero to the number of buffers + allocated with the :ref:`VIDIOC_REQBUFS` ioctl + (struct :c:type:`v4l2_requestbuffers` + ``count``), plus any buffers allocated with + :ref:`VIDIOC_CREATE_BUFS` minus one. + * - __u32 + - ``type`` + - Type of the buffer, same as struct + :c:type:`v4l2_format` ``type`` or struct + :c:type:`v4l2_requestbuffers` ``type``, set + by the application. See :c:type:`v4l2_buf_type` + * - __u32 + - ``bytesused`` + - The number of bytes occupied by the data in the buffer. It depends + on the negotiated data format and may change with each buffer for + compressed variable size data like JPEG images. Drivers must set + this field when ``type`` refers to a capture stream, applications + when it refers to an output stream. If the application sets this + to 0 for an output stream, then ``bytesused`` will be set to the + size of the buffer (see the ``length`` field of this struct) by + the driver. For multiplanar formats this field is ignored and the + ``planes`` pointer is used instead. + * - __u32 + - ``flags`` + - Flags set by the application or driver, see :ref:`buffer-flags`. + * - __u32 + - ``field`` + - Indicates the field order of the image in the buffer, see + :c:type:`v4l2_field`. This field is not used when the buffer + contains VBI data. Drivers must set it when ``type`` refers to a + capture stream, applications when it refers to an output stream. + * - struct timeval + - ``timestamp`` + - For capture streams this is time when the first data byte was + captured, as returned by the :c:func:`clock_gettime()` function + for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in + :ref:`buffer-flags`. For output streams the driver stores the + time at which the last data byte was actually sent out in the + ``timestamp`` field. This permits applications to monitor the + drift between the video and system clock. For output streams that + use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill + in the timestamp which will be copied by the driver to the capture + stream. + * - struct :c:type:`v4l2_timecode` + - ``timecode`` + - When the ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this + structure contains a frame timecode. In + :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and + bottom field contain the same timecode. Timecodes are intended to + help video editing and are typically recorded on video tapes, but + also embedded in compressed formats like MPEG. This field is + independent of the ``timestamp`` and ``sequence`` fields. + * - __u32 + - ``sequence`` + - Set by the driver, counting the frames (not fields!) in sequence. + This field is set for both input and output devices. + * - :cspan:`2` + + In :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and + bottom field have the same sequence number. The count starts at + zero and includes dropped or repeated frames. A dropped frame was + received by an input device but could not be stored due to lack of + free buffer space. A repeated frame was displayed again by an + output device because the application did not pass new data in + time. + + .. note:: + + This may count the frames received e.g. over USB, without + taking into account the frames dropped by the remote hardware due + to limited compression throughput or bus bandwidth. These devices + identify by not enumerating any video standards, see + :ref:`standard`. + + * - __u32 + - ``memory`` + - This field must be set by applications and/or drivers in + accordance with the selected I/O method. See :c:type:`v4l2_memory` + * - union { + - ``m`` + * - __u32 + - ``offset`` + - For the single-planar API and when ``memory`` is + ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the + start of the device memory. The value is returned by the driver + and apart of serving as parameter to the + :c:func:`mmap()` function not useful for applications. + See :ref:`mmap` for details + * - unsigned long + - ``userptr`` + - For the single-planar API and when ``memory`` is + ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to + unsigned long type) in virtual memory, set by the application. See + :ref:`userp` for details. + * - struct v4l2_plane + - ``*planes`` + - When using the multi-planar API, contains a userspace pointer to + an array of struct :c:type:`v4l2_plane`. The size of + the array should be put in the ``length`` field of this + struct :c:type:`v4l2_buffer` structure. + * - int + - ``fd`` + - For the single-plane API and when ``memory`` is + ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with + a DMABUF buffer. + * - } + - + * - __u32 + - ``length`` + - Size of the buffer (not the payload) in bytes for the + single-planar API. This is set by the driver based on the calls to + :ref:`VIDIOC_REQBUFS` and/or + :ref:`VIDIOC_CREATE_BUFS`. For the + multi-planar API the application sets this to the number of + elements in the ``planes`` array. The driver will fill in the + actual number of valid elements in that array. + * - __u32 + - ``reserved2`` + - A place holder for future extensions. Drivers and applications + must set this to 0. + * - __u32 + - ``request_fd`` + - The file descriptor of the request to queue the buffer to. If the flag + ``V4L2_BUF_FLAG_REQUEST_FD`` is set, then the buffer will be + queued to this request. If the flag is not set, then this field will + be ignored. + + The ``V4L2_BUF_FLAG_REQUEST_FD`` flag and this field are only used by + :ref:`ioctl VIDIOC_QBUF <VIDIOC_QBUF>` and ignored by other ioctls that + take a :c:type:`v4l2_buffer` as argument. + + Applications should not set ``V4L2_BUF_FLAG_REQUEST_FD`` for any ioctls + other than :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. + + If the device does not support requests, then ``EBADR`` will be returned. + If requests are supported but an invalid request file descriptor is + given, then ``EINVAL`` will be returned. + + +.. c:type:: v4l2_plane + +struct v4l2_plane +================= + +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{10.3cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``bytesused`` + - The number of bytes occupied by data in the plane (its payload). + Drivers must set this field when ``type`` refers to a capture + stream, applications when it refers to an output stream. If the + application sets this to 0 for an output stream, then + ``bytesused`` will be set to the size of the plane (see the + ``length`` field of this struct) by the driver. + + .. note:: + + Note that the actual image data starts at ``data_offset`` + which may not be 0. + * - __u32 + - ``length`` + - Size in bytes of the plane (not its payload). This is set by the + driver based on the calls to + :ref:`VIDIOC_REQBUFS` and/or + :ref:`VIDIOC_CREATE_BUFS`. + * - union { + - ``m`` + * - __u32 + - ``mem_offset`` + - When the memory type in the containing struct + :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this + is the value that should be passed to :c:func:`mmap()`, + similar to the ``offset`` field in struct + :c:type:`v4l2_buffer`. + * - unsigned long + - ``userptr`` + - When the memory type in the containing struct + :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``, + this is a userspace pointer to the memory allocated for this plane + by an application. + * - int + - ``fd`` + - When the memory type in the containing struct + :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``, + this is a file descriptor associated with a DMABUF buffer, similar + to the ``fd`` field in struct :c:type:`v4l2_buffer`. + * - } + - + * - __u32 + - ``data_offset`` + - Offset in bytes to video data in the plane. Drivers must set this + field when ``type`` refers to a capture stream, applications when + it refers to an output stream. + + .. note:: + + That data_offset is included in ``bytesused``. So the + size of the image in the plane is ``bytesused``-``data_offset`` + at offset ``data_offset`` from the start of the plane. + * - __u32 + - ``reserved[11]`` + - Reserved for future use. Should be zeroed by drivers and + applications. + + +.. c:type:: v4l2_buf_type + +enum v4l2_buf_type +================== + +.. cssclass:: longtable + +.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{8.9cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 4 1 9 + + * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` + - 1 + - Buffer of a single-planar video capture stream, see + :ref:`capture`. + * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` + - 9 + - Buffer of a multi-planar video capture stream, see + :ref:`capture`. + * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` + - 2 + - Buffer of a single-planar video output stream, see + :ref:`output`. + * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` + - 10 + - Buffer of a multi-planar video output stream, see :ref:`output`. + * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` + - 3 + - Buffer for video overlay, see :ref:`overlay`. + * - ``V4L2_BUF_TYPE_VBI_CAPTURE`` + - 4 + - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`. + * - ``V4L2_BUF_TYPE_VBI_OUTPUT`` + - 5 + - Buffer of a raw VBI output stream, see :ref:`raw-vbi`. + * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` + - 6 + - Buffer of a sliced VBI capture stream, see :ref:`sliced`. + * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` + - 7 + - Buffer of a sliced VBI output stream, see :ref:`sliced`. + * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` + - 8 + - Buffer for video output overlay (OSD), see :ref:`osd`. + * - ``V4L2_BUF_TYPE_SDR_CAPTURE`` + - 11 + - Buffer for Software Defined Radio (SDR) capture stream, see + :ref:`sdr`. + * - ``V4L2_BUF_TYPE_SDR_OUTPUT`` + - 12 + - Buffer for Software Defined Radio (SDR) output stream, see + :ref:`sdr`. + * - ``V4L2_BUF_TYPE_META_CAPTURE`` + - 13 + - Buffer for metadata capture, see :ref:`metadata`. + * - ``V4L2_BUF_TYPE_META_OUTPUT`` + - 14 + - Buffer for metadata output, see :ref:`metadata`. + + +.. _buffer-flags: + +Buffer Flags +============ + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{6.5cm}|p{1.8cm}|p{9.0cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 65 18 70 + + * .. _`V4L2-BUF-FLAG-MAPPED`: + + - ``V4L2_BUF_FLAG_MAPPED`` + - 0x00000001 + - The buffer resides in device memory and has been mapped into the + application's address space, see :ref:`mmap` for details. + Drivers set or clear this flag when the + :ref:`VIDIOC_QUERYBUF`, + :ref:`VIDIOC_QBUF` or + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the + driver. + * .. _`V4L2-BUF-FLAG-QUEUED`: + + - ``V4L2_BUF_FLAG_QUEUED`` + - 0x00000002 + - Internally drivers maintain two buffer queues, an incoming and + outgoing queue. When this flag is set, the buffer is currently on + the incoming queue. It automatically moves to the outgoing queue + after the buffer has been filled (capture devices) or displayed + (output devices). Drivers set or clear this flag when the + ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling + the ``VIDIOC_QBUF``\ ioctl it is always set and after + ``VIDIOC_DQBUF`` always cleared. + * .. _`V4L2-BUF-FLAG-DONE`: + + - ``V4L2_BUF_FLAG_DONE`` + - 0x00000004 + - When this flag is set, the buffer is currently on the outgoing + queue, ready to be dequeued from the driver. Drivers set or clear + this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After + calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always + cleared. Of course a buffer cannot be on both queues at the same + time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag + are mutually exclusive. They can be both cleared however, then the + buffer is in "dequeued" state, in the application domain so to + say. + * .. _`V4L2-BUF-FLAG-ERROR`: + + - ``V4L2_BUF_FLAG_ERROR`` + - 0x00000040 + - When this flag is set, the buffer has been dequeued successfully, + although the data might have been corrupted. This is recoverable, + streaming may continue as normal and the buffer may be reused + normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is + called. + * .. _`V4L2-BUF-FLAG-IN-REQUEST`: + + - ``V4L2_BUF_FLAG_IN_REQUEST`` + - 0x00000080 + - This buffer is part of a request that hasn't been queued yet. + * .. _`V4L2-BUF-FLAG-KEYFRAME`: + + - ``V4L2_BUF_FLAG_KEYFRAME`` + - 0x00000008 + - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF`` + ioctl. It may be set by video capture devices when the buffer + contains a compressed image which is a key frame (or field), i. e. + can be decompressed on its own. Also known as an I-frame. + Applications can set this bit when ``type`` refers to an output + stream. + * .. _`V4L2-BUF-FLAG-PFRAME`: + + - ``V4L2_BUF_FLAG_PFRAME`` + - 0x00000010 + - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames + or fields which contain only differences to a previous key frame. + Applications can set this bit when ``type`` refers to an output + stream. + * .. _`V4L2-BUF-FLAG-BFRAME`: + + - ``V4L2_BUF_FLAG_BFRAME`` + - 0x00000020 + - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional + predicted frame or field which contains only the differences + between the current frame and both the preceding and following key + frames to specify its content. Applications can set this bit when + ``type`` refers to an output stream. + * .. _`V4L2-BUF-FLAG-TIMECODE`: + + - ``V4L2_BUF_FLAG_TIMECODE`` + - 0x00000100 + - The ``timecode`` field is valid. Drivers set or clear this flag + when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set + this bit and the corresponding ``timecode`` structure when + ``type`` refers to an output stream. + * .. _`V4L2-BUF-FLAG-PREPARED`: + + - ``V4L2_BUF_FLAG_PREPARED`` + - 0x00000400 + - The buffer has been prepared for I/O and can be queued by the + application. Drivers set or clear this flag when the + :ref:`VIDIOC_QUERYBUF`, + :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`, + :ref:`VIDIOC_QBUF` or + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. + * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: + + - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` + - 0x00000800 + - Caches do not have to be invalidated for this buffer. Typically + applications shall use this flag if the data captured in the + buffer is not going to be touched by the CPU, instead the buffer + will, probably, be passed on to a DMA-capable hardware unit for + further processing or output. This flag is ignored unless the + queue is used for :ref:`memory mapping <mmap>` streaming I/O and + reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. + * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`: + + - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` + - 0x00001000 + - Caches do not have to be cleaned for this buffer. Typically + applications shall use this flag for output buffers if the data in + this buffer has not been created by the CPU but by some + DMA-capable unit, in which case caches have not been used. This flag + is ignored unless the queue is used for :ref:`memory mapping <mmap>` + streaming I/O and reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. + * .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`: + + - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` + - 0x00000200 + - Only valid if struct :c:type:`v4l2_requestbuffers` flag ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is + set. It is typically used with stateless decoders where multiple + output buffers each decode to a slice of the decoded frame. + Applications can set this flag when queueing the output buffer + to prevent the driver from dequeueing the capture buffer after + the output buffer has been decoded (i.e. the capture buffer is + 'held'). If the timestamp of this output buffer differs from that + of the previous output buffer, then that indicates the start of a + new frame and the previously held capture buffer is dequeued. + * .. _`V4L2-BUF-FLAG-LAST`: + + - ``V4L2_BUF_FLAG_LAST`` + - 0x00100000 + - Last buffer produced by the hardware. mem2mem codec drivers set + this flag on the capture queue for the last buffer when the + :ref:`VIDIOC_QUERYBUF` or + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to + hardware limitations, the last buffer may be empty. In this case + the driver will set the ``bytesused`` field to 0, regardless of + the format. Any subsequent call to the + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, + but return an ``EPIPE`` error code. + * .. _`V4L2-BUF-FLAG-REQUEST-FD`: + + - ``V4L2_BUF_FLAG_REQUEST_FD`` + - 0x00800000 + - The ``request_fd`` field contains a valid file descriptor. + * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`: + + - ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` + - 0x0000e000 + - Mask for timestamp types below. To test the timestamp type, mask + out bits not belonging to timestamp type by performing a logical + and operation with buffer flags and timestamp mask. + * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`: + + - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN`` + - 0x00000000 + - Unknown timestamp type. This type is used by drivers before Linux + 3.9 and may be either monotonic (see below) or realtime (wall + clock). Monotonic clock has been favoured in embedded systems + whereas most of the drivers use the realtime clock. Either kinds + of timestamps are available in user space via + :c:func:`clock_gettime` using clock IDs ``CLOCK_MONOTONIC`` + and ``CLOCK_REALTIME``, respectively. + * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`: + + - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC`` + - 0x00002000 + - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC`` + clock. To access the same clock outside V4L2, use + :c:func:`clock_gettime`. + * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`: + + - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` + - 0x00004000 + - The CAPTURE buffer timestamp has been taken from the corresponding + OUTPUT buffer. This flag applies only to mem2mem devices. + * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`: + + - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` + - 0x00070000 + - Mask for timestamp sources below. The timestamp source defines the + point of time the timestamp is taken in relation to the frame. + Logical 'and' operation between the ``flags`` field and + ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the + timestamp source. Applications must set the timestamp source when + ``type`` refers to an output stream and + ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set. + * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`: + + - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF`` + - 0x00000000 + - End Of Frame. The buffer timestamp has been taken when the last + pixel of the frame has been received or the last pixel of the + frame has been transmitted. In practice, software generated + timestamps will typically be read from the clock a small amount of + time after the last pixel has been received or transmitten, + depending on the system and other activity in it. + * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`: + + - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE`` + - 0x00010000 + - Start Of Exposure. The buffer timestamp has been taken when the + exposure of the frame has begun. This is only valid for the + ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. + +.. raw:: latex + + \normalsize + +enum v4l2_memory +================ + +.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_MEMORY_MMAP`` + - 1 + - The buffer is used for :ref:`memory mapping <mmap>` I/O. + * - ``V4L2_MEMORY_USERPTR`` + - 2 + - The buffer is used for :ref:`user pointer <userp>` I/O. + * - ``V4L2_MEMORY_OVERLAY`` + - 3 + - [to do] + * - ``V4L2_MEMORY_DMABUF`` + - 4 + - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O. + +.. _memory-flags: + +Memory Consistency Flags +------------------------ + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`V4L2-MEMORY-FLAG-NON-COHERENT`: + + - ``V4L2_MEMORY_FLAG_NON_COHERENT`` + - 0x00000001 + - A buffer is allocated either in coherent (it will be automatically + coherent between the CPU and the bus) or non-coherent memory. The + latter can provide performance gains, for instance the CPU cache + sync/flush operations can be avoided if the buffer is accessed by the + corresponding device only and the CPU does not read/write to/from that + buffer. However, this requires extra care from the driver -- it must + guarantee memory consistency by issuing a cache flush/sync when + consistency is needed. If this flag is set V4L2 will attempt to + allocate the buffer in non-coherent memory. The flag takes effect + only if the buffer is used for :ref:`memory mapping <mmap>` I/O and the + queue reports the :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. + +.. raw:: latex + + \normalsize + +Timecodes +========= + +The :c:type:`v4l2_buffer_timecode` structure is designed to hold a +:ref:`smpte12m` or similar timecode. +(struct :c:type:`timeval` timestamps are stored in the struct +:c:type:`v4l2_buffer` ``timestamp`` field.) + +.. c:type:: v4l2_timecode + +struct v4l2_timecode +-------------------- + +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``type`` + - Frame rate the timecodes are based on, see :ref:`timecode-type`. + * - __u32 + - ``flags`` + - Timecode flags, see :ref:`timecode-flags`. + * - __u8 + - ``frames`` + - Frame count, 0 ... 23/24/29/49/59, depending on the type of + timecode. + * - __u8 + - ``seconds`` + - Seconds count, 0 ... 59. This is a binary, not BCD number. + * - __u8 + - ``minutes`` + - Minutes count, 0 ... 59. This is a binary, not BCD number. + * - __u8 + - ``hours`` + - Hours count, 0 ... 29. This is a binary, not BCD number. + * - __u8 + - ``userbits``\ [4] + - The "user group" bits from the timecode. + + +.. _timecode-type: + +Timecode Types +-------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_TC_TYPE_24FPS`` + - 1 + - 24 frames per second, i. e. film. + * - ``V4L2_TC_TYPE_25FPS`` + - 2 + - 25 frames per second, i. e. PAL or SECAM video. + * - ``V4L2_TC_TYPE_30FPS`` + - 3 + - 30 frames per second, i. e. NTSC video. + * - ``V4L2_TC_TYPE_50FPS`` + - 4 + - + * - ``V4L2_TC_TYPE_60FPS`` + - 5 + - + + +.. _timecode-flags: + +Timecode Flags +-------------- + +.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_TC_FLAG_DROPFRAME`` + - 0x0001 + - Indicates "drop frame" semantics for counting frames in 29.97 fps + material. When set, frame numbers 0 and 1 at the start of each + minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the + count. + * - ``V4L2_TC_FLAG_COLORFRAME`` + - 0x0002 + - The "color frame" flag. + * - ``V4L2_TC_USERBITS_field`` + - 0x000C + - Field mask for the "binary group flags". + * - ``V4L2_TC_USERBITS_USERDEFINED`` + - 0x0000 + - Unspecified format. + * - ``V4L2_TC_USERBITS_8BITCHARS`` + - 0x0008 + - 8-bit ISO characters. |