0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_QBUF:
0005
0006 *******************************
0007 ioctl VIDIOC_QBUF, VIDIOC_DQBUF
0008 *******************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_QBUF
0019
0020 ``int ioctl(int fd, VIDIOC_QBUF, struct v4l2_buffer *argp)``
0021
0022 .. c:macro:: VIDIOC_DQBUF
0023
0024 ``int ioctl(int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_buffer`.
0034
0035 Description
0036 ===========
0037
0038 Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty
0039 (capturing) or filled (output) buffer in the driver's incoming queue.
0040 The semantics depend on the selected I/O method.
0041
0042 To enqueue a buffer applications set the ``type`` field of a struct
0043 :c:type:`v4l2_buffer` to the same buffer type as was
0044 previously used with struct :c:type:`v4l2_format` ``type``
0045 and struct :c:type:`v4l2_requestbuffers` ``type``.
0046 Applications must also set the ``index`` field. Valid index numbers
0047 range from zero to the number of buffers allocated with
0048 :ref:`VIDIOC_REQBUFS` (struct
0049 :c:type:`v4l2_requestbuffers` ``count``) minus
0050 one. The contents of the struct :c:type:`v4l2_buffer` returned
0051 by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well.
0052 When the buffer is intended for output (``type`` is
0053 ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
0054 or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the
0055 ``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`
0056 for details. Applications must also set ``flags`` to 0. The
0057 ``reserved2`` and ``reserved`` fields must be set to 0. When using the
0058 :ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must
0059 contain a userspace pointer to a filled-in array of struct
0060 :c:type:`v4l2_plane` and the ``length`` field must be set
0061 to the number of elements in that array.
0062
0063 To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
0064 ``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called
0065 with a pointer to this structure the driver sets the
0066 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears
0067 the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an
0068 ``EINVAL`` error code.
0069
0070 To enqueue a :ref:`user pointer <userp>` buffer applications set the
0071 ``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
0072 the address of the buffer and ``length`` to its size. When the
0073 multi-planar API is used, ``m.userptr`` and ``length`` members of the
0074 passed array of struct :c:type:`v4l2_plane` have to be used
0075 instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure
0076 the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
0077 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
0078 ``flags`` field, or it returns an error code. This ioctl locks the
0079 memory pages of the buffer in physical memory, they cannot be swapped
0080 out to disk. Buffers remain locked until dequeued, until the
0081 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
0082 :ref:`VIDIOC_REQBUFS` ioctl is called, or until the
0083 device is closed.
0084
0085 To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the
0086 ``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a
0087 file descriptor associated with a DMABUF buffer. When the multi-planar
0088 API is used the ``m.fd`` fields of the passed array of struct
0089 :c:type:`v4l2_plane` have to be used instead. When
0090 ``VIDIOC_QBUF`` is called with a pointer to this structure the driver
0091 sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
0092 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
0093 ``flags`` field, or it returns an error code. This ioctl locks the
0094 buffer. Locking a buffer means passing it to a driver for a hardware
0095 access (usually DMA). If an application accesses (reads/writes) a locked
0096 buffer then the result is undefined. Buffers remain locked until
0097 dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
0098 :ref:`VIDIOC_REQBUFS` ioctl is called, or until the
0099 device is closed.
0100
0101 The ``request_fd`` field can be used with the ``VIDIOC_QBUF`` ioctl to specify
0102 the file descriptor of a :ref:`request <media-request-api>`, if requests are
0103 in use. Setting it means that the buffer will not be passed to the driver
0104 until the request itself is queued. Also, the driver will apply any
0105 settings associated with the request for this buffer. This field will
0106 be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set.
0107 If the device does not support requests, then ``EBADR`` will be returned.
0108 If requests are supported but an invalid request file descriptor is given,
0109 then ``EINVAL`` will be returned.
0110
0111 .. caution::
0112 It is not allowed to mix queuing requests with queuing buffers directly.
0113 ``EBUSY`` will be returned if the first buffer was queued directly and
0114 then the application tries to queue a request, or vice versa. After
0115 closing the file descriptor, calling
0116 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS`
0117 the check for this will be reset.
0118
0119 For :ref:`memory-to-memory devices <mem2mem>` you can specify the
0120 ``request_fd`` only for output buffers, not for capture buffers. Attempting
0121 to specify this for a capture buffer will result in an ``EBADR`` error.
0122
0123 Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
0124 (capturing) or displayed (output) buffer from the driver's outgoing
0125 queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
0126 a struct :c:type:`v4l2_buffer` as above, when
0127 ``VIDIOC_DQBUF`` is called with a pointer to this structure the driver
0128 fills all remaining fields or returns an error code. The driver may also
0129 set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a
0130 non-critical (recoverable) streaming error. In such case the application
0131 may continue as normal, but should be aware that data in the dequeued
0132 buffer might be corrupted. When using the multi-planar API, the planes
0133 array must be passed in as well.
0134
0135 If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to
0136 dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field
0137 with a file descriptor numerically the same as the one given to ``VIDIOC_QBUF``
0138 when the buffer was enqueued. No new file descriptor is created at dequeue time
0139 and the value is only for the application convenience. When the multi-planar
0140 API is used the ``m.fd`` fields of the passed array of struct
0141 :c:type:`v4l2_plane` are filled instead.
0142
0143 By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing
0144 queue. When the ``O_NONBLOCK`` flag was given to the
0145 :c:func:`open()` function, ``VIDIOC_DQBUF`` returns
0146 immediately with an ``EAGAIN`` error code when no buffer is available.
0147
0148 The struct :c:type:`v4l2_buffer` structure is specified in
0149 :ref:`buffer`.
0150
0151 Return Value
0152 ============
0153
0154 On success 0 is returned, on error -1 and the ``errno`` variable is set
0155 appropriately. The generic error codes are described at the
0156 :ref:`Generic Error Codes <gen-errors>` chapter.
0157
0158 EAGAIN
0159 Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
0160 buffer was in the outgoing queue.
0161
0162 EINVAL
0163 The buffer ``type`` is not supported, or the ``index`` is out of
0164 bounds, or no buffers have been allocated yet, or the ``userptr`` or
0165 ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was
0166 set but the given ``request_fd`` was invalid, or ``m.fd`` was
0167 an invalid DMABUF file descriptor.
0168
0169 EIO
0170 ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate
0171 temporary problems like signal loss.
0172
0173 .. note::
0174
0175 The driver might dequeue an (empty) buffer despite returning
0176 an error, or even stop capturing. Reusing such buffer may be unsafe
0177 though and its details (e.g. ``index``) may not be returned either.
0178 It is recommended that drivers indicate recoverable errors by setting
0179 the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the
0180 application should be able to safely reuse the buffer and continue
0181 streaming.
0182
0183 EPIPE
0184 ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem
0185 codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already
0186 dequeued and no new buffers are expected to become available.
0187
0188 EBADR
0189 The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not
0190 support requests for the given buffer type, or
0191 the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires
0192 that the buffer is part of a request.
0193
0194 EBUSY
0195 The first buffer was queued via a request, but the application now tries
0196 to queue it directly, or vice versa (it is not permitted to mix the two
0197 APIs).
