1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _VIDIOC_QBUF:
5
6*******************************
7ioctl VIDIOC_QBUF, VIDIOC_DQBUF
8*******************************
9
10Name
11====
12
13VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver
14
15Synopsis
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
26Arguments
27=========
28
29``fd``
30    File descriptor returned by :c:func:`open()`.
31
32``argp``
33    Pointer to struct :c:type:`v4l2_buffer`.
34
35Description
36===========
37
38Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty
39(capturing) or filled (output) buffer in the driver's incoming queue.
40The semantics depend on the selected I/O method.
41
42To enqueue a buffer applications set the ``type`` field of a struct
43:c:type:`v4l2_buffer` to the same buffer type as was
44previously used with struct :c:type:`v4l2_format` ``type``
45and struct :c:type:`v4l2_requestbuffers` ``type``.
46Applications must also set the ``index`` field. Valid index numbers
47range from zero to the number of buffers allocated with
48:ref:`VIDIOC_REQBUFS` (struct
49:c:type:`v4l2_requestbuffers` ``count``) minus
50one. The contents of the struct :c:type:`v4l2_buffer` returned
51by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well.
52When the buffer is intended for output (``type`` is
53``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
54or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the
55``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`
56for 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
59contain a userspace pointer to a filled-in array of struct
60:c:type:`v4l2_plane` and the ``length`` field must be set
61to the number of elements in that array.
62
63To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
64``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called
65with a pointer to this structure the driver sets the
66``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears
67the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an
68``EINVAL`` error code.
69
70To enqueue a :ref:`user pointer <userp>` buffer applications set the
71``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
72the address of the buffer and ``length`` to its size. When the
73multi-planar API is used, ``m.userptr`` and ``length`` members of the
74passed array of struct :c:type:`v4l2_plane` have to be used
75instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure
76the 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
79memory pages of the buffer in physical memory, they cannot be swapped
80out 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
83device is closed.
84
85To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the
86``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a
87file descriptor associated with a DMABUF buffer. When the multi-planar
88API 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
91sets 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
94buffer. Locking a buffer means passing it to a driver for a hardware
95access (usually DMA). If an application accesses (reads/writes) a locked
96buffer then the result is undefined. Buffers remain locked until
97dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
98:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
99device is closed.
100
101The ``request_fd`` field can be used with the ``VIDIOC_QBUF`` ioctl to specify
102the file descriptor of a :ref:`request <media-request-api>`, if requests are
103in use. Setting it means that the buffer will not be passed to the driver
104until the request itself is queued. Also, the driver will apply any
105settings associated with the request for this buffer. This field will
106be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set.
107If the device does not support requests, then ``EBADR`` will be returned.
108If requests are supported but an invalid request file descriptor is given,
109then ``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
123Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
124(capturing) or displayed (output) buffer from the driver's outgoing
125queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
126a struct :c:type:`v4l2_buffer` as above, when
127``VIDIOC_DQBUF`` is called with a pointer to this structure the driver
128fills all remaining fields or returns an error code. The driver may also
129set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a
130non-critical (recoverable) streaming error. In such case the application
131may continue as normal, but should be aware that data in the dequeued
132buffer might be corrupted. When using the multi-planar API, the planes
133array must be passed in as well.
134
135If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to
136dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field
137with a file descriptor numerically the same as the one given to ``VIDIOC_QBUF``
138when the buffer was enqueued. No new file descriptor is created at dequeue time
139and the value is only for the application convenience. When the multi-planar
140API is used the ``m.fd`` fields of the passed array of struct
141:c:type:`v4l2_plane` are filled instead.
142
143By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing
144queue. When the ``O_NONBLOCK`` flag was given to the
145:c:func:`open()` function, ``VIDIOC_DQBUF`` returns
146immediately with an ``EAGAIN`` error code when no buffer is available.
147
148The struct :c:type:`v4l2_buffer` structure is specified in
149:ref:`buffer`.
150
151Return Value
152============
153
154On success 0 is returned, on error -1 and the ``errno`` variable is set
155appropriately. The generic error codes are described at the
156:ref:`Generic Error Codes <gen-errors>` chapter.
157
158EAGAIN
159    Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
160    buffer was in the outgoing queue.
161
162EINVAL
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
169EIO
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
183EPIPE
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
188EBADR
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
194EBUSY
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).
198