aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/v4l/vidioc-qbuf.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/v4l/vidioc-qbuf.xml')
-rw-r--r--Documentation/DocBook/v4l/vidioc-qbuf.xml168
1 files changed, 168 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml
new file mode 100644
index 000000000000..187081778154
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml
@@ -0,0 +1,168 @@
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 <link linkend="mmap">memory mapped</link>
58buffer applications set the <structfield>type</structfield> field of a
59&v4l2-buffer; to the same buffer type as previously &v4l2-format;
60<structfield>type</structfield> and &v4l2-requestbuffers;
61<structfield>type</structfield>, the <structfield>memory</structfield>
62field to <constant>V4L2_MEMORY_MMAP</constant> and the
63<structfield>index</structfield> field. Valid index numbers range from
64zero to the number of buffers allocated with &VIDIOC-REQBUFS;
65(&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The
66contents of the struct <structname>v4l2_buffer</structname> returned
67by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is
68intended for output (<structfield>type</structfield> is
69<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
70<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
71initialize the <structfield>bytesused</structfield>,
72<structfield>field</structfield> and
73<structfield>timestamp</structfield> fields. See <xref
74 linkend="buffer" /> for details. When
75<constant>VIDIOC_QBUF</constant> is called with a pointer to this
76structure the driver sets the
77<constant>V4L2_BUF_FLAG_MAPPED</constant> and
78<constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the
79<constant>V4L2_BUF_FLAG_DONE</constant> flag in the
80<structfield>flags</structfield> field, or it returns an
81&EINVAL;.</para>
82
83 <para>To enqueue a <link linkend="userp">user pointer</link>
84buffer applications set the <structfield>type</structfield> field of a
85&v4l2-buffer; to the same buffer type as previously &v4l2-format;
86<structfield>type</structfield> and &v4l2-requestbuffers;
87<structfield>type</structfield>, the <structfield>memory</structfield>
88field to <constant>V4L2_MEMORY_USERPTR</constant> and the
89<structfield>m.userptr</structfield> field to the address of the
90buffer and <structfield>length</structfield> to its size. When the
91buffer is intended for output additional fields must be set as above.
92When <constant>VIDIOC_QBUF</constant> is called with a pointer to this
93structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant>
94flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and
95<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
96<structfield>flags</structfield> field, or it returns an error code.
97This ioctl locks the memory pages of the buffer in physical memory,
98they cannot be swapped out to disk. Buffers remain locked until
99dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl are
100called, or until the device is closed.</para>
101
102 <para>Applications call the <constant>VIDIOC_DQBUF</constant>
103ioctl to dequeue a filled (capturing) or displayed (output) buffer
104from the driver's outgoing queue. They just set the
105<structfield>type</structfield> and <structfield>memory</structfield>
106fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
107is called with a pointer to this structure the driver fills the
108remaining fields or returns an error code.</para>
109
110 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
111buffer is in the outgoing queue. When the
112<constant>O_NONBLOCK</constant> flag was given to the &func-open;
113function, <constant>VIDIOC_DQBUF</constant> returns immediately
114with an &EAGAIN; when no buffer is available.</para>
115
116 <para>The <structname>v4l2_buffer</structname> structure is
117specified in <xref linkend="buffer" />.</para>
118 </refsect1>
119
120 <refsect1>
121 &return-value;
122
123 <variablelist>
124 <varlistentry>
125 <term><errorcode>EAGAIN</errorcode></term>
126 <listitem>
127 <para>Non-blocking I/O has been selected using
128<constant>O_NONBLOCK</constant> and no buffer was in the outgoing
129queue.</para>
130 </listitem>
131 </varlistentry>
132 <varlistentry>
133 <term><errorcode>EINVAL</errorcode></term>
134 <listitem>
135 <para>The buffer <structfield>type</structfield> is not
136supported, or the <structfield>index</structfield> is out of bounds,
137or no buffers have been allocated yet, or the
138<structfield>userptr</structfield> or
139<structfield>length</structfield> are invalid.</para>
140 </listitem>
141 </varlistentry>
142 <varlistentry>
143 <term><errorcode>ENOMEM</errorcode></term>
144 <listitem>
145 <para>Not enough physical or virtual memory was available to
146enqueue a user pointer buffer.</para>
147 </listitem>
148 </varlistentry>
149 <varlistentry>
150 <term><errorcode>EIO</errorcode></term>
151 <listitem>
152 <para><constant>VIDIOC_DQBUF</constant> failed due to an
153internal error. Can also indicate temporary problems like signal
154loss. Note the driver might dequeue an (empty) buffer despite
155returning an error, or even stop capturing.</para>
156 </listitem>
157 </varlistentry>
158 </variablelist>
159 </refsect1>
160</refentry>
161
162<!--
163Local Variables:
164mode: sgml
165sgml-parent-document: "v4l2.sgml"
166indent-tabs-mode: nil
167End:
168-->
generated by cgit v1.2.2 (git 2.25.0) at 2024-12-30 11:02:18 -0500