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> 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. 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> 82 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> 93 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> 111 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> 128 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> 142 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> 148 149 <para>The <structname>v4l2_buffer</structname> structure is 150 specified in <xref linkend="buffer" />.</para> 151 </refsect1> 152 153 <refsect1> 154 &return-value; 155 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>
