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