About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / vidioc-qbuf.xml

Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.

1	<refentry id="vidioc-qbuf">
2	  <refmeta>
3	    <refentrytitle>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</refentrytitle>
4	    &manvol;
5	  </refmeta>
7	  <refnamediv>
8	    <refname>VIDIOC_QBUF</refname>
9	    <refname>VIDIOC_DQBUF</refname>
10	    <refpurpose>Exchange a buffer with the driver</refpurpose>
11	  </refnamediv>
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>
24	  <refsect1>
25	    <title>Arguments</title>
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>
49	  <refsect1>
50	    <title>Description</title>
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>
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>,
68	<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or
69	<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
70	initialize the <structfield>bytesused</structfield>,
71	<structfield>field</structfield> and
72	<structfield>timestamp</structfield> fields, see <xref
73	linkend="buffer" /> for details.
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
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.
81	</para>
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
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>
94	    <para>To enqueue a <link linkend="userp">user pointer</link>
95	buffer applications set the <structfield>memory</structfield>
96	field to <constant>V4L2_MEMORY_USERPTR</constant>, the
97	<structfield>m.userptr</structfield> field to the address of the
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
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
109	dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is
110	called, or until the device is closed.</para>
112	    <para>To enqueue a <link linkend="dmabuf">DMABUF</link> buffer applications
113	set the <structfield>memory</structfield> field to
114	<constant>V4L2_MEMORY_DMABUF</constant> and the <structfield>m.fd</structfield>
115	field to a file descriptor associated with a DMABUF buffer. When the
116	multi-planar API is used the <structfield>m.fd</structfield> fields of the
117	passed array of &v4l2-plane; have to be used instead. When
118	<constant>VIDIOC_QBUF</constant> is called with a pointer to this structure the
119	driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the
120	<constant>V4L2_BUF_FLAG_MAPPED</constant> and
121	<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
122	<structfield>flags</structfield> field, or it returns an error code.  This
123	ioctl locks the buffer. Locking a buffer means passing it to a driver for a
124	hardware access (usually DMA).  If an application accesses (reads/writes) a
125	locked buffer then the result is undefined.  Buffers remain locked until
126	dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or
127	until the device is closed.</para>
129	    <para>Applications call the <constant>VIDIOC_DQBUF</constant>
130	ioctl to dequeue a filled (capturing) or displayed (output) buffer
131	from the driver's outgoing queue. They just set the
132	<structfield>type</structfield>, <structfield>memory</structfield>
133	and <structfield>reserved</structfield>
134	fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
135	is called with a pointer to this structure the driver fills the
136	remaining fields or returns an error code. The driver may also set
137	<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
138	field. It indicates a non-critical (recoverable) streaming error. In such case
139	the application may continue as normal, but should be aware that data in the
140	dequeued buffer might be corrupted. When using the multi-planar API, the
141	planes array must be passed in as well.</para>
143	    <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
144	buffer is in the outgoing queue. When the
145	<constant>O_NONBLOCK</constant> flag was given to the &func-open;
146	function, <constant>VIDIOC_DQBUF</constant> returns immediately
147	with an &EAGAIN; when no buffer is available.</para>
149	    <para>The <structname>v4l2_buffer</structname> structure is
150	specified in <xref linkend="buffer" />.</para>
151	  </refsect1>
153	  <refsect1>
154	    &return-value;
156	    <variablelist>
157	      <varlistentry>
158		<term><errorcode>EAGAIN</errorcode></term>
159		<listitem>
160		  <para>Non-blocking I/O has been selected using
161	<constant>O_NONBLOCK</constant> and no buffer was in the outgoing
162	queue.</para>
163		</listitem>
164	      </varlistentry>
165	      <varlistentry>
166		<term><errorcode>EINVAL</errorcode></term>
167		<listitem>
168		  <para>The buffer <structfield>type</structfield> is not
169	supported, or the <structfield>index</structfield> is out of bounds,
170	or no buffers have been allocated yet, or the
171	<structfield>userptr</structfield> or
172	<structfield>length</structfield> are invalid.</para>
173		</listitem>
174	      </varlistentry>
175	      <varlistentry>
176		<term><errorcode>EIO</errorcode></term>
177		<listitem>
178		  <para><constant>VIDIOC_DQBUF</constant> failed due to an
179	internal error. Can also indicate temporary problems like signal
180	loss. Note the driver might dequeue an (empty) buffer despite
181	returning an error, or even stop capturing. Reusing such buffer may be unsafe
182	though and its details (e.g. <structfield>index</structfield>) may not be
183	returned either. It is recommended that drivers indicate recoverable errors
184	by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead.
185	In that case the application should be able to safely reuse the buffer and
186	continue streaming.
187		</para>
188		</listitem>
189	      </varlistentry>
190	      <varlistentry>
191		<term><errorcode>EPIPE</errorcode></term>
192		<listitem>
193		  <para><constant>VIDIOC_DQBUF</constant> returns this on an empty
194	capture queue for mem2mem codecs if a buffer with the
195	<constant>V4L2_BUF_FLAG_LAST</constant> was already dequeued and no new buffers
196	are expected to become available.
197		  </para>
198		</listitem>
199	      </varlistentry>
200	    </variablelist>
201	  </refsect1>
202	</refentry>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.