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