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