Check-in of baseline 2.6.34 tree
[linux-2.6.34-lpc32xx.git] / Documentation / DocBook / v4l / vidioc-qbuf.xml
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
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
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
67 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
68 <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
69 initialize the <structfield>bytesused</structfield>,
70 <structfield>field</structfield> and
71 <structfield>timestamp</structfield> fields, see <xref
72 linkend="buffer" /> for details.
73 Applications must also set <structfield>flags</structfield> to 0. If a driver
74 supports capturing from specific video inputs and you want to specify a video
75 input, 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.
78 The <structfield>reserved</structfield> field must be set to 0.
79 </para>
80
81     <para>To enqueue a <link linkend="mmap">memory mapped</link>
82 buffer applications set the <structfield>memory</structfield>
83 field to <constant>V4L2_MEMORY_MMAP</constant>. When
84 <constant>VIDIOC_QBUF</constant> is called with a pointer to this
85 structure 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>
93 buffer applications set the <structfield>memory</structfield>
94 field to <constant>V4L2_MEMORY_USERPTR</constant>, the
95 <structfield>m.userptr</structfield> field to the address of the
96 buffer and <structfield>length</structfield> to its size.
97 When <constant>VIDIOC_QBUF</constant> is called with a pointer to this
98 structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant>
99 flag 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.
102 This ioctl locks the memory pages of the buffer in physical memory,
103 they cannot be swapped out to disk. Buffers remain locked until
104 dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is
105 called, or until the device is closed.</para>
106
107     <para>Applications call the <constant>VIDIOC_DQBUF</constant>
108 ioctl to dequeue a filled (capturing) or displayed (output) buffer
109 from the driver's outgoing queue. They just set the
110 <structfield>type</structfield>, <structfield>memory</structfield>
111 and <structfield>reserved</structfield>
112 fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
113 is called with a pointer to this structure the driver fills the
114 remaining fields or returns an error code.</para>
115
116     <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
117 buffer is in the outgoing queue. When the
118 <constant>O_NONBLOCK</constant> flag was given to the &func-open;
119 function, <constant>VIDIOC_DQBUF</constant> returns immediately
120 with an &EAGAIN; when no buffer is available.</para>
121
122     <para>The <structname>v4l2_buffer</structname> structure is
123 specified in <xref linkend="buffer" />.</para>
124   </refsect1>
125
126   <refsect1>
127     &return-value;
128
129     <variablelist>
130       <varlistentry>
131         <term><errorcode>EAGAIN</errorcode></term>
132         <listitem>
133           <para>Non-blocking I/O has been selected using
134 <constant>O_NONBLOCK</constant> and no buffer was in the outgoing
135 queue.</para>
136         </listitem>
137       </varlistentry>
138       <varlistentry>
139         <term><errorcode>EINVAL</errorcode></term>
140         <listitem>
141           <para>The buffer <structfield>type</structfield> is not
142 supported, or the <structfield>index</structfield> is out of bounds,
143 or no buffers have been allocated yet, or the
144 <structfield>userptr</structfield> or
145 <structfield>length</structfield> are invalid.</para>
146         </listitem>
147       </varlistentry>
148       <varlistentry>
149         <term><errorcode>ENOMEM</errorcode></term>
150         <listitem>
151           <para>Not enough physical or virtual memory was available to
152 enqueue a user pointer buffer.</para>
153         </listitem>
154       </varlistentry>
155       <varlistentry>
156         <term><errorcode>EIO</errorcode></term>
157         <listitem>
158           <para><constant>VIDIOC_DQBUF</constant> failed due to an
159 internal error. Can also indicate temporary problems like signal
160 loss. Note the driver might dequeue an (empty) buffer despite
161 returning an error, or even stop capturing.</para>
162         </listitem>
163       </varlistentry>
164     </variablelist>
165   </refsect1>
166 </refentry>
167
168 <!--
169 Local Variables:
170 mode: sgml
171 sgml-parent-document: "v4l2.sgml"
172 indent-tabs-mode: nil
173 End:
174 -->