Commit | Line | Data |
---|---|---|
8e080c2e MCC |
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 | |
53 | to enqueue an empty (capturing) or filled (output) buffer in the | |
54 | driver's incoming queue. The semantics depend on the selected I/O | |
55 | method.</para> | |
56 | ||
995f5fef HV |
57 | <para>To enqueue a buffer applications set the <structfield>type</structfield> |
58 | field of a &v4l2-buffer; to the same buffer type as was previously used | |
59 | with &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers; | |
60 | <structfield>type</structfield>. Applications must also set the | |
8e080c2e MCC |
61 | <structfield>index</structfield> field. Valid index numbers range from |
62 | zero to the number of buffers allocated with &VIDIOC-REQBUFS; | |
63 | (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The | |
64 | contents of the struct <structname>v4l2_buffer</structname> returned | |
65 | by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is | |
66 | intended for output (<structfield>type</structfield> is | |
53b5d574 PO |
67 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, |
68 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or | |
8e080c2e MCC |
69 | <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also |
70 | initialize the <structfield>bytesused</structfield>, | |
71 | <structfield>field</structfield> and | |
995f5fef HV |
72 | <structfield>timestamp</structfield> fields, see <xref |
73 | linkend="buffer" /> for details. | |
2b719d7b SA |
74 | Applications must also set <structfield>flags</structfield> to 0. |
75 | The <structfield>reserved2</structfield> and | |
76 | <structfield>reserved</structfield> fields must be set to 0. When using | |
53b5d574 PO |
77 | the <link linkend="planar-apis">multi-planar API</link>, the |
78 | <structfield>m.planes</structfield> field must contain a userspace pointer | |
79 | to a filled-in array of &v4l2-plane; and the <structfield>length</structfield> | |
80 | field must be set to the number of elements in that array. | |
995f5fef HV |
81 | </para> |
82 | ||
83 | <para>To enqueue a <link linkend="mmap">memory mapped</link> | |
84 | buffer applications set the <structfield>memory</structfield> | |
85 | field to <constant>V4L2_MEMORY_MMAP</constant>. When | |
8e080c2e MCC |
86 | <constant>VIDIOC_QBUF</constant> is called with a pointer to this |
87 | structure 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> | |
995f5fef HV |
95 | buffer applications set the <structfield>memory</structfield> |
96 | field to <constant>V4L2_MEMORY_USERPTR</constant>, the | |
8e080c2e | 97 | <structfield>m.userptr</structfield> field to the address of the |
53b5d574 PO |
98 | buffer and <structfield>length</structfield> to its size. When the multi-planar |
99 | API is used, <structfield>m.userptr</structfield> and | |
100 | <structfield>length</structfield> members of the passed array of &v4l2-plane; | |
101 | have to be used instead. When <constant>VIDIOC_QBUF</constant> is called with | |
102 | a 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 | |
8e080c2e MCC |
105 | <constant>V4L2_BUF_FLAG_DONE</constant> flags in the |
106 | <structfield>flags</structfield> field, or it returns an error code. | |
107 | This ioctl locks the memory pages of the buffer in physical memory, | |
108 | they cannot be swapped out to disk. Buffers remain locked until | |
995f5fef | 109 | dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is |
8e080c2e MCC |
110 | called, or until the device is closed.</para> |
111 | ||
112 | <para>Applications call the <constant>VIDIOC_DQBUF</constant> | |
113 | ioctl to dequeue a filled (capturing) or displayed (output) buffer | |
114 | from the driver's outgoing queue. They just set the | |
995f5fef HV |
115 | <structfield>type</structfield>, <structfield>memory</structfield> |
116 | and <structfield>reserved</structfield> | |
8e080c2e MCC |
117 | fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant> |
118 | is called with a pointer to this structure the driver fills the | |
21636363 PO |
119 | remaining fields or returns an error code. The driver may also set |
120 | <constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield> | |
121 | field. It indicates a non-critical (recoverable) streaming error. In such case | |
122 | the application may continue as normal, but should be aware that data in the | |
53b5d574 PO |
123 | dequeued buffer might be corrupted. When using the multi-planar API, the |
124 | planes array does not have to be passed; the <structfield>m.planes</structfield> | |
125 | member must be set to NULL in that case.</para> | |
8e080c2e MCC |
126 | |
127 | <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no | |
128 | buffer is in the outgoing queue. When the | |
129 | <constant>O_NONBLOCK</constant> flag was given to the &func-open; | |
130 | function, <constant>VIDIOC_DQBUF</constant> returns immediately | |
131 | with an &EAGAIN; when no buffer is available.</para> | |
132 | ||
133 | <para>The <structname>v4l2_buffer</structname> structure is | |
134 | specified in <xref linkend="buffer" />.</para> | |
135 | </refsect1> | |
136 | ||
137 | <refsect1> | |
138 | &return-value; | |
139 | ||
140 | <variablelist> | |
141 | <varlistentry> | |
142 | <term><errorcode>EAGAIN</errorcode></term> | |
143 | <listitem> | |
144 | <para>Non-blocking I/O has been selected using | |
145 | <constant>O_NONBLOCK</constant> and no buffer was in the outgoing | |
146 | queue.</para> | |
147 | </listitem> | |
148 | </varlistentry> | |
149 | <varlistentry> | |
150 | <term><errorcode>EINVAL</errorcode></term> | |
151 | <listitem> | |
152 | <para>The buffer <structfield>type</structfield> is not | |
153 | supported, or the <structfield>index</structfield> is out of bounds, | |
154 | or no buffers have been allocated yet, or the | |
155 | <structfield>userptr</structfield> or | |
156 | <structfield>length</structfield> are invalid.</para> | |
157 | </listitem> | |
8e080c2e MCC |
158 | <term><errorcode>EIO</errorcode></term> |
159 | <listitem> | |
160 | <para><constant>VIDIOC_DQBUF</constant> failed due to an | |
161 | internal error. Can also indicate temporary problems like signal | |
162 | loss. Note the driver might dequeue an (empty) buffer despite | |
21636363 PO |
163 | returning an error, or even stop capturing. Reusing such buffer may be unsafe |
164 | though and its details (e.g. <structfield>index</structfield>) may not be | |
165 | returned either. It is recommended that drivers indicate recoverable errors | |
166 | by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead. | |
167 | In that case the application should be able to safely reuse the buffer and | |
168 | continue streaming. | |
169 | </para> | |
8e080c2e MCC |
170 | </listitem> |
171 | </varlistentry> | |
172 | </variablelist> | |
173 | </refsect1> | |
174 | </refentry> |