1 .. Permission is granted to copy, distribute and/or modify this
2 .. document under the terms of the GNU Free Documentation License,
3 .. Version 1.1 or any later version published by the Free Software
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
12 *******************************
13 ioctl VIDIOC_QBUF, VIDIOC_DQBUF
14 *******************************
19 VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver
25 .. c:function:: int ioctl( int fd, VIDIOC_QBUF, struct v4l2_buffer *argp )
28 .. c:function:: int ioctl( int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp )
36 File descriptor returned by :ref:`open() <func-open>`.
39 Pointer to struct :c:type:`v4l2_buffer`.
45 Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty
46 (capturing) or filled (output) buffer in the driver's incoming queue.
47 The semantics depend on the selected I/O method.
49 To enqueue a buffer applications set the ``type`` field of a struct
50 :c:type:`v4l2_buffer` to the same buffer type as was
51 previously used with struct :c:type:`v4l2_format` ``type``
52 and struct :c:type:`v4l2_requestbuffers` ``type``.
53 Applications must also set the ``index`` field. Valid index numbers
54 range from zero to the number of buffers allocated with
55 :ref:`VIDIOC_REQBUFS` (struct
56 :c:type:`v4l2_requestbuffers` ``count``) minus
57 one. The contents of the struct :c:type:`v4l2_buffer` returned
58 by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well.
59 When the buffer is intended for output (``type`` is
60 ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
61 or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the
62 ``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`
63 for details. Applications must also set ``flags`` to 0. The
64 ``reserved2`` and ``reserved`` fields must be set to 0. When using the
65 :ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must
66 contain a userspace pointer to a filled-in array of struct
67 :c:type:`v4l2_plane` and the ``length`` field must be set
68 to the number of elements in that array.
70 To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
71 ``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called
72 with a pointer to this structure the driver sets the
73 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears
74 the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an
75 ``EINVAL`` error code.
77 To enqueue a :ref:`user pointer <userp>` buffer applications set the
78 ``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
79 the address of the buffer and ``length`` to its size. When the
80 multi-planar API is used, ``m.userptr`` and ``length`` members of the
81 passed array of struct :c:type:`v4l2_plane` have to be used
82 instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure
83 the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
84 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
85 ``flags`` field, or it returns an error code. This ioctl locks the
86 memory pages of the buffer in physical memory, they cannot be swapped
87 out to disk. Buffers remain locked until dequeued, until the
88 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
89 :ref:`VIDIOC_REQBUFS` ioctl is called, or until the
92 To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the
93 ``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a
94 file descriptor associated with a DMABUF buffer. When the multi-planar
95 API is used the ``m.fd`` fields of the passed array of struct
96 :c:type:`v4l2_plane` have to be used instead. When
97 ``VIDIOC_QBUF`` is called with a pointer to this structure the driver
98 sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
99 ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
100 ``flags`` field, or it returns an error code. This ioctl locks the
101 buffer. Locking a buffer means passing it to a driver for a hardware
102 access (usually DMA). If an application accesses (reads/writes) a locked
103 buffer then the result is undefined. Buffers remain locked until
104 dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
105 :ref:`VIDIOC_REQBUFS` ioctl is called, or until the
108 The ``request_fd`` field can be used with the ``VIDIOC_QBUF`` ioctl to specify
109 the file descriptor of a :ref:`request <media-request-api>`, if requests are
110 in use. Setting it means that the buffer will not be passed to the driver
111 until the request itself is queued. Also, the driver will apply any
112 settings associated with the request for this buffer. This field will
113 be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set.
114 If the device does not support requests, then ``EACCES`` will be returned.
115 If requests are supported but an invalid request file descriptor is given,
116 then ``EINVAL`` will be returned.
119 It is not allowed to mix queuing requests with queuing buffers directly.
120 ``EBUSY`` will be returned if the first buffer was queued directly and
121 then the application tries to queue a request, or vice versa. After
122 closing the file descriptor, calling
123 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS`
124 the check for this will be reset.
126 For :ref:`memory-to-memory devices <codec>` you can specify the
127 ``request_fd`` only for output buffers, not for capture buffers. Attempting
128 to specify this for a capture buffer will result in an ``EACCES`` error.
130 Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
131 (capturing) or displayed (output) buffer from the driver's outgoing
132 queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
133 a struct :c:type:`v4l2_buffer` as above, when
134 ``VIDIOC_DQBUF`` is called with a pointer to this structure the driver
135 fills the remaining fields or returns an error code. The driver may also
136 set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a
137 non-critical (recoverable) streaming error. In such case the application
138 may continue as normal, but should be aware that data in the dequeued
139 buffer might be corrupted. When using the multi-planar API, the planes
140 array must be passed in as well.
142 By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing
143 queue. When the ``O_NONBLOCK`` flag was given to the
144 :ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns
145 immediately with an ``EAGAIN`` error code when no buffer is available.
147 The struct :c:type:`v4l2_buffer` structure is specified in
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.
159 Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
160 buffer was in the outgoing queue.
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 the given ``request_fd`` was invalid, or ``m.fd`` was
167 an invalid DMABUF file descriptor.
170 ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate
171 temporary problems like signal loss.
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
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.
189 The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not
190 support requests for the given buffer type.
193 The first buffer was queued via a request, but the application now tries
194 to queue it directly, or vice versa (it is not permitted to mix the two