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