1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 .. c:namespace:: V4L 3 4 .. _VIDIOC_QBUF: 5 6 ******************************* 7 ioctl VIDIOC_QBUF, VIDIOC_DQBUF 8 ******************************* 9 10 Name 11 ==== 12 13 VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver 14 15 Synopsis 16 ======== 17 18 .. c:macro:: VIDIOC_QBUF 19 20 ``int ioctl(int fd, VIDIOC_QBUF, struct v4l2_buffer *argp)`` 21 22 .. c:macro:: VIDIOC_DQBUF 23 24 ``int ioctl(int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp)`` 25 26 Arguments 27 ========= 28 29 ``fd`` 30 File descriptor returned by :c:func:`open()`. 31 32 ``argp`` 33 Pointer to struct :c:type:`v4l2_buffer`. 34 35 Description 36 =========== 37 38 Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty 39 (capturing) or filled (output) buffer in the driver's incoming queue. 40 The semantics depend on the selected I/O method. 41 42 To enqueue a buffer applications set the ``type`` field of a struct 43 :c:type:`v4l2_buffer` to the same buffer type as was 44 previously used with struct :c:type:`v4l2_format` ``type`` 45 and struct :c:type:`v4l2_requestbuffers` ``type``. 46 Applications must also set the ``index`` field. Valid index numbers 47 range from zero to the number of buffers allocated with 48 :ref:`VIDIOC_REQBUFS` (struct 49 :c:type:`v4l2_requestbuffers` ``count``) minus 50 one. The contents of the struct :c:type:`v4l2_buffer` returned 51 by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well. 52 When the buffer is intended for output (``type`` is 53 ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``, 54 or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the 55 ``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer` 56 for details. Applications must also set ``flags`` to 0. The 57 ``reserved2`` and ``reserved`` fields must be set to 0. When using the 58 :ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must 59 contain a userspace pointer to a filled-in array of struct 60 :c:type:`v4l2_plane` and the ``length`` field must be set 61 to the number of elements in that array. 62 63 To enqueue a :ref:`memory mapped <mmap>` buffer applications set the 64 ``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called 65 with a pointer to this structure the driver sets the 66 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears 67 the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an 68 ``EINVAL`` error code. 69 70 To enqueue a :ref:`user pointer <userp>` buffer applications set the 71 ``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to 72 the address of the buffer and ``length`` to its size. When the 73 multi-planar API is used, ``m.userptr`` and ``length`` members of the 74 passed array of struct :c:type:`v4l2_plane` have to be used 75 instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure 76 the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the 77 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the 78 ``flags`` field, or it returns an error code. This ioctl locks the 79 memory pages of the buffer in physical memory, they cannot be swapped 80 out to disk. Buffers remain locked until dequeued, until the 81 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or 82 :ref:`VIDIOC_REQBUFS` ioctl is called, or until the 83 device is closed. 84 85 To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the 86 ``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a 87 file descriptor associated with a DMABUF buffer. When the multi-planar 88 API is used the ``m.fd`` fields of the passed array of struct 89 :c:type:`v4l2_plane` have to be used instead. When 90 ``VIDIOC_QBUF`` is called with a pointer to this structure the driver 91 sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the 92 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the 93 ``flags`` field, or it returns an error code. This ioctl locks the 94 buffer. Locking a buffer means passing it to a driver for a hardware 95 access (usually DMA). If an application accesses (reads/writes) a locked 96 buffer then the result is undefined. Buffers remain locked until 97 dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or 98 :ref:`VIDIOC_REQBUFS` ioctl is called, or until the 99 device is closed. 100 101 The ``request_fd`` field can be used with the ``VIDIOC_QBUF`` ioctl to specify 102 the file descriptor of a :ref:`request <media-request-api>`, if requests are 103 in use. Setting it means that the buffer will not be passed to the driver 104 until the request itself is queued. Also, the driver will apply any 105 settings associated with the request for this buffer. This field will 106 be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set. 107 If the device does not support requests, then ``EBADR`` will be returned. 108 If requests are supported but an invalid request file descriptor is given, 109 then ``EINVAL`` will be returned. 110 111 .. caution:: 112 It is not allowed to mix queuing requests with queuing buffers directly. 113 ``EBUSY`` will be returned if the first buffer was queued directly and 114 then the application tries to queue a request, or vice versa. After 115 closing the file descriptor, calling 116 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS` 117 the check for this will be reset. 118 119 For :ref:`memory-to-memory devices <mem2mem>` you can specify the 120 ``request_fd`` only for output buffers, not for capture buffers. Attempting 121 to specify this for a capture buffer will result in an ``EBADR`` error. 122 123 Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled 124 (capturing) or displayed (output) buffer from the driver's outgoing 125 queue. They just set the ``type``, ``memory`` and ``reserved`` fields of 126 a struct :c:type:`v4l2_buffer` as above, when 127 ``VIDIOC_DQBUF`` is called with a pointer to this structure the driver 128 fills all remaining fields or returns an error code. The driver may also 129 set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a 130 non-critical (recoverable) streaming error. In such case the application 131 may continue as normal, but should be aware that data in the dequeued 132 buffer might be corrupted. When using the multi-planar API, the planes 133 array must be passed in as well. 134 135 If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to 136 dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field 137 with a file descriptor numerically the same as the one given to ``VIDIOC_QBUF`` 138 when the buffer was enqueued. No new file descriptor is created at dequeue time 139 and the value is only for the application convenience. When the multi-planar 140 API is used the ``m.fd`` fields of the passed array of struct 141 :c:type:`v4l2_plane` are filled instead. 142 143 By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing 144 queue. When the ``O_NONBLOCK`` flag was given to the 145 :c:func:`open()` function, ``VIDIOC_DQBUF`` returns 146 immediately with an ``EAGAIN`` error code when no buffer is available. 147 148 The struct :c:type:`v4l2_buffer` structure is specified in 149 :ref:`buffer`. 150 151 Return Value 152 ============ 153 154 On success 0 is returned, on error -1 and the ``errno`` variable is set 155 appropriately. The generic error codes are described at the 156 :ref:`Generic Error Codes <gen-errors>` chapter. 157 158 EAGAIN 159 Non-blocking I/O has been selected using ``O_NONBLOCK`` and no 160 buffer was in the outgoing queue. 161 162 EINVAL 163 The buffer ``type`` is not supported, or the ``index`` is out of 164 bounds, or no buffers have been allocated yet, or the ``userptr`` or 165 ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was 166 set but the given ``request_fd`` was invalid, or ``m.fd`` was 167 an invalid DMABUF file descriptor. 168 169 EIO 170 ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate 171 temporary problems like signal loss. 172 173 .. note:: 174 175 The driver might dequeue an (empty) buffer despite returning 176 an error, or even stop capturing. Reusing such buffer may be unsafe 177 though and its details (e.g. ``index``) may not be returned either. 178 It is recommended that drivers indicate recoverable errors by setting 179 the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the 180 application should be able to safely reuse the buffer and continue 181 streaming. 182 183 EPIPE 184 ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem 185 codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already 186 dequeued and no new buffers are expected to become available. 187 188 EBADR 189 The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not 190 support requests for the given buffer type, or 191 the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires 192 that the buffer is part of a request. 193 194 EBUSY 195 The first buffer was queued via a request, but the application now tries 196 to queue it directly, or vice versa (it is not permitted to mix the two 197 APIs).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.