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 buffer applications set the <structfield>type</structfield> 58field of a &v4l2-buffer; to the same buffer type as was previously used 59with &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 62zero to the number of buffers allocated with &VIDIOC-REQBUFS; 63(&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The 64contents of the struct <structname>v4l2_buffer</structname> returned 65by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is 66intended 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 69initialize the <structfield>bytesused</structfield>, 70<structfield>field</structfield> and 71<structfield>timestamp</structfield> fields, see <xref 72linkend="buffer" /> for details. 73Applications must also set <structfield>flags</structfield> to 0. If a driver 74supports capturing from specific video inputs and you want to specify a video 75input, 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. 78The <structfield>reserved</structfield> field must be set to 0. 79</para> 80 81 <para>To enqueue a <link linkend="mmap">memory mapped</link> 82buffer applications set the <structfield>memory</structfield> 83field to <constant>V4L2_MEMORY_MMAP</constant>. When 84<constant>VIDIOC_QBUF</constant> is called with a pointer to this 85structure 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> 93buffer applications set the <structfield>memory</structfield> 94field to <constant>V4L2_MEMORY_USERPTR</constant>, the 95<structfield>m.userptr</structfield> field to the address of the 96buffer and <structfield>length</structfield> to its size. 97When <constant>VIDIOC_QBUF</constant> is called with a pointer to this 98structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> 99flag 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. 102This ioctl locks the memory pages of the buffer in physical memory, 103they cannot be swapped out to disk. Buffers remain locked until 104dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is 105called, or until the device is closed.</para> 106 107 <para>Applications call the <constant>VIDIOC_DQBUF</constant> 108ioctl to dequeue a filled (capturing) or displayed (output) buffer 109from the driver's outgoing queue. They just set the 110<structfield>type</structfield>, <structfield>memory</structfield> 111and <structfield>reserved</structfield> 112fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant> 113is called with a pointer to this structure the driver fills the 114remaining fields or returns an error code. The driver may also set 115<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield> 116field. It indicates a non-critical (recoverable) streaming error. In such case 117the application may continue as normal, but should be aware that data in the 118dequeued buffer might be corrupted.</para> 119 120 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no 121buffer is in the outgoing queue. When the 122<constant>O_NONBLOCK</constant> flag was given to the &func-open; 123function, <constant>VIDIOC_DQBUF</constant> returns immediately 124with an &EAGAIN; when no buffer is available.</para> 125 126 <para>The <structname>v4l2_buffer</structname> structure is 127specified in <xref linkend="buffer" />.</para> 128 </refsect1> 129 130 <refsect1> 131 &return-value; 132 133 <variablelist> 134 <varlistentry> 135 <term><errorcode>EAGAIN</errorcode></term> 136 <listitem> 137 <para>Non-blocking I/O has been selected using 138<constant>O_NONBLOCK</constant> and no buffer was in the outgoing 139queue.</para> 140 </listitem> 141 </varlistentry> 142 <varlistentry> 143 <term><errorcode>EINVAL</errorcode></term> 144 <listitem> 145 <para>The buffer <structfield>type</structfield> is not 146supported, or the <structfield>index</structfield> is out of bounds, 147or no buffers have been allocated yet, or the 148<structfield>userptr</structfield> or 149<structfield>length</structfield> are invalid.</para> 150 </listitem> 151 </varlistentry> 152 <varlistentry> 153 <term><errorcode>ENOMEM</errorcode></term> 154 <listitem> 155 <para>Not enough physical or virtual memory was available to 156enqueue a user pointer buffer.</para> 157 </listitem> 158 </varlistentry> 159 <varlistentry> 160 <term><errorcode>EIO</errorcode></term> 161 <listitem> 162 <para><constant>VIDIOC_DQBUF</constant> failed due to an 163internal error. Can also indicate temporary problems like signal 164loss. Note the driver might dequeue an (empty) buffer despite 165returning an error, or even stop capturing. Reusing such buffer may be unsafe 166though and its details (e.g. <structfield>index</structfield>) may not be 167returned either. It is recommended that drivers indicate recoverable errors 168by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead. 169In that case the application should be able to safely reuse the buffer and 170continue streaming. 171 </para> 172 </listitem> 173 </varlistentry> 174 </variablelist> 175 </refsect1> 176</refentry> 177 178<!-- 179Local Variables: 180mode: sgml 181sgml-parent-document: "v4l2.sgml" 182indent-tabs-mode: nil 183End: 184--> 185