1<refentry id="vidioc-qbuf">
2  <refmeta>
3    <refentrytitle>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</refentrytitle>
4    &manvol;
5  </refmeta>
6
7  <refnamediv>
8    <refname>VIDIOC_QBUF</refname>
9    <refname>VIDIOC_DQBUF</refname>
10    <refpurpose>Exchange a buffer with the driver</refpurpose>
11  </refnamediv>
12
13  <refsynopsisdiv>
14    <funcsynopsis>
15      <funcprototype>
16	<funcdef>int <function>ioctl</function></funcdef>
17	<paramdef>int <parameter>fd</parameter></paramdef>
18	<paramdef>int <parameter>request</parameter></paramdef>
19	<paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef>
20      </funcprototype>
21    </funcsynopsis>
22  </refsynopsisdiv>
23
24  <refsect1>
25    <title>Arguments</title>
26
27    <variablelist>
28      <varlistentry>
29	<term><parameter>fd</parameter></term>
30	<listitem>
31	  <para>&fd;</para>
32	</listitem>
33      </varlistentry>
34      <varlistentry>
35	<term><parameter>request</parameter></term>
36	<listitem>
37	  <para>VIDIOC_QBUF, VIDIOC_DQBUF</para>
38	</listitem>
39      </varlistentry>
40      <varlistentry>
41	<term><parameter>argp</parameter></term>
42	<listitem>
43	  <para></para>
44	</listitem>
45      </varlistentry>
46    </variablelist>
47  </refsect1>
48
49  <refsect1>
50    <title>Description</title>
51
52    <para>Applications call the <constant>VIDIOC_QBUF</constant> ioctl
53to enqueue an empty (capturing) or filled (output) buffer in the
54driver's incoming queue. The semantics depend on the selected I/O
55method.</para>
56
57    <para>To enqueue a buffer applications set the <structfield>type</structfield>
58field of a &v4l2-buffer; to the same buffer type as was previously used
59with &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers;
60<structfield>type</structfield>. Applications must also set the
61<structfield>index</structfield> field. Valid index numbers range from
62zero to the number of buffers allocated with &VIDIOC-REQBUFS;
63(&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The
64contents of the struct <structname>v4l2_buffer</structname> returned
65by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is
66intended for output (<structfield>type</structfield> is
67<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
68<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or
69<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
70initialize the <structfield>bytesused</structfield>,
71<structfield>field</structfield> and
72<structfield>timestamp</structfield> fields, see <xref
73linkend="buffer" /> for details.
74Applications must also set <structfield>flags</structfield> to 0.
75The <structfield>reserved2</structfield> and
76<structfield>reserved</structfield> fields must be set to 0. When using
77the <link linkend="planar-apis">multi-planar API</link>, the
78<structfield>m.planes</structfield> field must contain a userspace pointer
79to a filled-in array of &v4l2-plane; and the <structfield>length</structfield>
80field must be set to the number of elements in that array.
81</para>
82
83    <para>To enqueue a <link linkend="mmap">memory mapped</link>
84buffer applications set the <structfield>memory</structfield>
85field to <constant>V4L2_MEMORY_MMAP</constant>. When
86<constant>VIDIOC_QBUF</constant> is called with a pointer to this
87structure the driver sets the
88<constant>V4L2_BUF_FLAG_MAPPED</constant> and
89<constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the
90<constant>V4L2_BUF_FLAG_DONE</constant> flag in the
91<structfield>flags</structfield> field, or it returns an
92&EINVAL;.</para>
93
94    <para>To enqueue a <link linkend="userp">user pointer</link>
95buffer applications set the <structfield>memory</structfield>
96field to <constant>V4L2_MEMORY_USERPTR</constant>, the
97<structfield>m.userptr</structfield> field to the address of the
98buffer and <structfield>length</structfield> to its size. When the multi-planar
99API is used, <structfield>m.userptr</structfield> and
100<structfield>length</structfield> members of the passed array of &v4l2-plane;
101have to be used instead. When <constant>VIDIOC_QBUF</constant> is called with
102a pointer to this structure the driver sets the
103<constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the
104<constant>V4L2_BUF_FLAG_MAPPED</constant> and
105<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
106<structfield>flags</structfield> field, or it returns an error code.
107This ioctl locks the memory pages of the buffer in physical memory,
108they cannot be swapped out to disk. Buffers remain locked until
109dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is
110called, or until the device is closed.</para>
111
112    <para>To enqueue a <link linkend="dmabuf">DMABUF</link> buffer applications
113set the <structfield>memory</structfield> field to
114<constant>V4L2_MEMORY_DMABUF</constant> and the <structfield>m.fd</structfield>
115field to a file descriptor associated with a DMABUF buffer. When the
116multi-planar API is used the <structfield>m.fd</structfield> fields of the
117passed array of &v4l2-plane; have to be used instead. When
118<constant>VIDIOC_QBUF</constant> is called with a pointer to this structure the
119driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the
120<constant>V4L2_BUF_FLAG_MAPPED</constant> and
121<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
122<structfield>flags</structfield> field, or it returns an error code.  This
123ioctl locks the buffer. Locking a buffer means passing it to a driver for a
124hardware access (usually DMA).  If an application accesses (reads/writes) a
125locked buffer then the result is undefined.  Buffers remain locked until
126dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or
127until the device is closed.</para>
128
129    <para>Applications call the <constant>VIDIOC_DQBUF</constant>
130ioctl to dequeue a filled (capturing) or displayed (output) buffer
131from the driver's outgoing queue. They just set the
132<structfield>type</structfield>, <structfield>memory</structfield>
133and <structfield>reserved</structfield>
134fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
135is called with a pointer to this structure the driver fills the
136remaining fields or returns an error code. The driver may also set
137<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
138field. It indicates a non-critical (recoverable) streaming error. In such case
139the application may continue as normal, but should be aware that data in the
140dequeued buffer might be corrupted. When using the multi-planar API, the
141planes array must be passed in as well.</para>
142
143    <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
144buffer is in the outgoing queue. When the
145<constant>O_NONBLOCK</constant> flag was given to the &func-open;
146function, <constant>VIDIOC_DQBUF</constant> returns immediately
147with an &EAGAIN; when no buffer is available.</para>
148
149    <para>The <structname>v4l2_buffer</structname> structure is
150specified in <xref linkend="buffer" />.</para>
151  </refsect1>
152
153  <refsect1>
154    &return-value;
155
156    <variablelist>
157      <varlistentry>
158	<term><errorcode>EAGAIN</errorcode></term>
159	<listitem>
160	  <para>Non-blocking I/O has been selected using
161<constant>O_NONBLOCK</constant> and no buffer was in the outgoing
162queue.</para>
163	</listitem>
164      </varlistentry>
165      <varlistentry>
166	<term><errorcode>EINVAL</errorcode></term>
167	<listitem>
168	  <para>The buffer <structfield>type</structfield> is not
169supported, or the <structfield>index</structfield> is out of bounds,
170or no buffers have been allocated yet, or the
171<structfield>userptr</structfield> or
172<structfield>length</structfield> are invalid.</para>
173	</listitem>
174      </varlistentry>
175      <varlistentry>
176	<term><errorcode>EIO</errorcode></term>
177	<listitem>
178	  <para><constant>VIDIOC_DQBUF</constant> failed due to an
179internal error. Can also indicate temporary problems like signal
180loss. Note the driver might dequeue an (empty) buffer despite
181returning an error, or even stop capturing. Reusing such buffer may be unsafe
182though and its details (e.g. <structfield>index</structfield>) may not be
183returned either. It is recommended that drivers indicate recoverable errors
184by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead.
185In that case the application should be able to safely reuse the buffer and
186continue streaming.
187	</para>
188	</listitem>
189      </varlistentry>
190    </variablelist>
191  </refsect1>
192</refentry>
193