Based on kernel version 3.0.4. Page generated on 2011-10-03 22:07 EST.
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>, 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. If a driver 75 supports capturing from specific video inputs and you want to specify a video 76 input, then <structfield>flags</structfield> should be set to 77 <constant>V4L2_BUF_FLAG_INPUT</constant> and the field 78 <structfield>input</structfield> must be initialized to the desired input. 79 The <structfield>reserved</structfield> field must be set to 0. When using 80 the <link linkend="planar-apis">multi-planar API</link>, the 81 <structfield>m.planes</structfield> field must contain a userspace pointer 82 to a filled-in array of &v4l2-plane; and the <structfield>length</structfield> 83 field must be set to the number of elements in that array. 84 </para> 85 86 <para>To enqueue a <link linkend="mmap">memory mapped</link> 87 buffer applications set the <structfield>memory</structfield> 88 field to <constant>V4L2_MEMORY_MMAP</constant>. When 89 <constant>VIDIOC_QBUF</constant> is called with a pointer to this 90 structure the driver sets the 91 <constant>V4L2_BUF_FLAG_MAPPED</constant> and 92 <constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the 93 <constant>V4L2_BUF_FLAG_DONE</constant> flag in the 94 <structfield>flags</structfield> field, or it returns an 95 &EINVAL;.</para> 96 97 <para>To enqueue a <link linkend="userp">user pointer</link> 98 buffer applications set the <structfield>memory</structfield> 99 field to <constant>V4L2_MEMORY_USERPTR</constant>, the 100 <structfield>m.userptr</structfield> field to the address of the 101 buffer and <structfield>length</structfield> to its size. When the multi-planar 102 API is used, <structfield>m.userptr</structfield> and 103 <structfield>length</structfield> members of the passed array of &v4l2-plane; 104 have to be used instead. When <constant>VIDIOC_QBUF</constant> is called with 105 a pointer to this structure the driver sets the 106 <constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the 107 <constant>V4L2_BUF_FLAG_MAPPED</constant> and 108 <constant>V4L2_BUF_FLAG_DONE</constant> flags in the 109 <structfield>flags</structfield> field, or it returns an error code. 110 This ioctl locks the memory pages of the buffer in physical memory, 111 they cannot be swapped out to disk. Buffers remain locked until 112 dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is 113 called, or until the device is closed.</para> 114 115 <para>Applications call the <constant>VIDIOC_DQBUF</constant> 116 ioctl to dequeue a filled (capturing) or displayed (output) buffer 117 from the driver's outgoing queue. They just set the 118 <structfield>type</structfield>, <structfield>memory</structfield> 119 and <structfield>reserved</structfield> 120 fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant> 121 is called with a pointer to this structure the driver fills the 122 remaining fields or returns an error code. The driver may also set 123 <constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield> 124 field. It indicates a non-critical (recoverable) streaming error. In such case 125 the application may continue as normal, but should be aware that data in the 126 dequeued buffer might be corrupted. When using the multi-planar API, the 127 planes array does not have to be passed; the <structfield>m.planes</structfield> 128 member must be set to NULL in that case.</para> 129 130 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no 131 buffer is in the outgoing queue. When the 132 <constant>O_NONBLOCK</constant> flag was given to the &func-open; 133 function, <constant>VIDIOC_DQBUF</constant> returns immediately 134 with an &EAGAIN; when no buffer is available.</para> 135 136 <para>The <structname>v4l2_buffer</structname> structure is 137 specified in <xref linkend="buffer" />.</para> 138 </refsect1> 139 140 <refsect1> 141 &return-value; 142 143 <variablelist> 144 <varlistentry> 145 <term><errorcode>EAGAIN</errorcode></term> 146 <listitem> 147 <para>Non-blocking I/O has been selected using 148 <constant>O_NONBLOCK</constant> and no buffer was in the outgoing 149 queue.</para> 150 </listitem> 151 </varlistentry> 152 <varlistentry> 153 <term><errorcode>EINVAL</errorcode></term> 154 <listitem> 155 <para>The buffer <structfield>type</structfield> is not 156 supported, or the <structfield>index</structfield> is out of bounds, 157 or no buffers have been allocated yet, or the 158 <structfield>userptr</structfield> or 159 <structfield>length</structfield> are invalid.</para> 160 </listitem> 161 </varlistentry> 162 <varlistentry> 163 <term><errorcode>ENOMEM</errorcode></term> 164 <listitem> 165 <para>Not enough physical or virtual memory was available to 166 enqueue a user pointer buffer.</para> 167 </listitem> 168 </varlistentry> 169 <varlistentry> 170 <term><errorcode>EIO</errorcode></term> 171 <listitem> 172 <para><constant>VIDIOC_DQBUF</constant> failed due to an 173 internal error. Can also indicate temporary problems like signal 174 loss. Note the driver might dequeue an (empty) buffer despite 175 returning an error, or even stop capturing. Reusing such buffer may be unsafe 176 though and its details (e.g. <structfield>index</structfield>) may not be 177 returned either. It is recommended that drivers indicate recoverable errors 178 by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead. 179 In that case the application should be able to safely reuse the buffer and 180 continue streaming. 181 </para> 182 </listitem> 183 </varlistentry> 184 </variablelist> 185 </refsect1> 186 </refentry> 187 188 <!-- 189 Local Variables: 190 mode: sgml 191 sgml-parent-document: "v4l2.sgml" 192 indent-tabs-mode: nil 193 End: 194 -->
