tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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. If a driver
75supports capturing from specific video inputs and you want to specify a video
76input, then <structfield>flags</structfield> should be set to
77<constant>V4L2_BUF_FLAG_INPUT</constant> and the field
78<structfield>input</structfield> must be initialized to the desired input.
79The <structfield>reserved</structfield> field must be set to 0. When using
80the <link linkend="planar-apis">multi-planar API</link>, the
81<structfield>m.planes</structfield> field must contain a userspace pointer
82to a filled-in array of &v4l2-plane; and the <structfield>length</structfield>
83field must be set to the number of elements in that array.
84</para>
85
86 <para>To enqueue a <link linkend="mmap">memory mapped</link>
87buffer applications set the <structfield>memory</structfield>
88field to <constant>V4L2_MEMORY_MMAP</constant>. When
89<constant>VIDIOC_QBUF</constant> is called with a pointer to this
90structure the driver sets the
91<constant>V4L2_BUF_FLAG_MAPPED</constant> and
92<constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the
93<constant>V4L2_BUF_FLAG_DONE</constant> flag in the
94<structfield>flags</structfield> field, or it returns an
95&EINVAL;.</para>
96
97 <para>To enqueue a <link linkend="userp">user pointer</link>
98buffer applications set the <structfield>memory</structfield>
99field to <constant>V4L2_MEMORY_USERPTR</constant>, the
100<structfield>m.userptr</structfield> field to the address of the
101buffer and <structfield>length</structfield> to its size. When the multi-planar
102API is used, <structfield>m.userptr</structfield> and
103<structfield>length</structfield> members of the passed array of &v4l2-plane;
104have to be used instead. When <constant>VIDIOC_QBUF</constant> is called with
105a pointer to this structure the driver sets the
106<constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the
107<constant>V4L2_BUF_FLAG_MAPPED</constant> and
108<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
109<structfield>flags</structfield> field, or it returns an error code.
110This ioctl locks the memory pages of the buffer in physical memory,
111they cannot be swapped out to disk. Buffers remain locked until
112dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is
113called, or until the device is closed.</para>
114
115 <para>Applications call the <constant>VIDIOC_DQBUF</constant>
116ioctl to dequeue a filled (capturing) or displayed (output) buffer
117from the driver's outgoing queue. They just set the
118<structfield>type</structfield>, <structfield>memory</structfield>
119and <structfield>reserved</structfield>
120fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
121is called with a pointer to this structure the driver fills the
122remaining fields or returns an error code. The driver may also set
123<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
124field. It indicates a non-critical (recoverable) streaming error. In such case
125the application may continue as normal, but should be aware that data in the
126dequeued buffer might be corrupted. When using the multi-planar API, the
127planes array does not have to be passed; the <structfield>m.planes</structfield>
128member must be set to NULL in that case.</para>
129
130 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
131buffer is in the outgoing queue. When the
132<constant>O_NONBLOCK</constant> flag was given to the &func-open;
133function, <constant>VIDIOC_DQBUF</constant> returns immediately
134with an &EAGAIN; when no buffer is available.</para>
135
136 <para>The <structname>v4l2_buffer</structname> structure is
137specified in <xref linkend="buffer" />.</para>
138 </refsect1>
139
140 <refsect1>
141 &return-value;
142
143 <variablelist>
144 <varlistentry>
145 <term><errorcode>EAGAIN</errorcode></term>
146 <listitem>
147 <para>Non-blocking I/O has been selected using
148<constant>O_NONBLOCK</constant> and no buffer was in the outgoing
149queue.</para>
150 </listitem>
151 </varlistentry>
152 <varlistentry>
153 <term><errorcode>EINVAL</errorcode></term>
154 <listitem>
155 <para>The buffer <structfield>type</structfield> is not
156supported, or the <structfield>index</structfield> is out of bounds,
157or no buffers have been allocated yet, or the
158<structfield>userptr</structfield> or
159<structfield>length</structfield> are invalid.</para>
160 </listitem>
161 </varlistentry>
162 <varlistentry>
163 <term><errorcode>ENOMEM</errorcode></term>
164 <listitem>
165 <para>Not enough physical or virtual memory was available to
166enqueue a user pointer buffer.</para>
167 </listitem>
168 </varlistentry>
169 <varlistentry>
170 <term><errorcode>EIO</errorcode></term>
171 <listitem>
172 <para><constant>VIDIOC_DQBUF</constant> failed due to an
173internal error. Can also indicate temporary problems like signal
174loss. Note the driver might dequeue an (empty) buffer despite
175returning an error, or even stop capturing. Reusing such buffer may be unsafe
176though and its details (e.g. <structfield>index</structfield>) may not be
177returned either. It is recommended that drivers indicate recoverable errors
178by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead.
179In that case the application should be able to safely reuse the buffer and
180continue streaming.
181 </para>
182 </listitem>
183 </varlistentry>
184 </variablelist>
185 </refsect1>
186</refentry>
187
188<!--
189Local Variables:
190mode: sgml
191sgml-parent-document: "v4l2.sgml"
192indent-tabs-mode: nil
193End:
194-->