Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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 | |
Hans Verkuil | 995f5fe | 2010-02-20 09:41:03 -0300 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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 |
Pawel Osciak | 53b5d57 | 2011-01-07 01:41:33 -0300 | [diff] [blame] | 67 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, |
| 68 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 69 | <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also |
| 70 | initialize the <structfield>bytesused</structfield>, |
| 71 | <structfield>field</structfield> and |
Hans Verkuil | 995f5fe | 2010-02-20 09:41:03 -0300 | [diff] [blame] | 72 | <structfield>timestamp</structfield> fields, see <xref |
| 73 | linkend="buffer" /> for details. |
Sakari Ailus | 2b719d7 | 2012-05-02 09:40:03 -0300 | [diff] [blame] | 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 |
Pawel Osciak | 53b5d57 | 2011-01-07 01:41:33 -0300 | [diff] [blame] | 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. |
Hans Verkuil | 995f5fe | 2010-02-20 09:41:03 -0300 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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> |
Hans Verkuil | 995f5fe | 2010-02-20 09:41:03 -0300 | [diff] [blame] | 95 | buffer applications set the <structfield>memory</structfield> |
| 96 | field to <constant>V4L2_MEMORY_USERPTR</constant>, the |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 97 | <structfield>m.userptr</structfield> field to the address of the |
Pawel Osciak | 53b5d57 | 2011-01-07 01:41:33 -0300 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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 |
Hans Verkuil | 995f5fe | 2010-02-20 09:41:03 -0300 | [diff] [blame] | 109 | dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 110 | called, or until the device is closed.</para> |
| 111 | |
Tomasz Stanislawski | 4b9c1cb | 2012-06-14 10:37:36 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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 |
Hans Verkuil | 995f5fe | 2010-02-20 09:41:03 -0300 | [diff] [blame] | 132 | <structfield>type</structfield>, <structfield>memory</structfield> |
| 133 | and <structfield>reserved</structfield> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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 |
Pawel Osciak | 2163636 | 2010-04-28 04:05:23 -0300 | [diff] [blame] | 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 |
Pawel Osciak | 53b5d57 | 2011-01-07 01:41:33 -0300 | [diff] [blame] | 140 | dequeued buffer might be corrupted. When using the multi-planar API, the |
Hans Verkuil | e3b1b4e | 2012-09-19 11:14:39 -0300 | [diff] [blame] | 141 | planes array must be passed in as well.</para> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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> |
Hans Verkuil | 071408b | 2012-08-14 06:10:01 -0300 | [diff] [blame] | 174 | </varlistentry> |
| 175 | <varlistentry> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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 |
Pawel Osciak | 2163636 | 2010-04-28 04:05:23 -0300 | [diff] [blame] | 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> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 188 | </listitem> |
Hans Verkuil | 9cae84b | 2015-05-15 07:28:02 -0300 | [diff] [blame] | 189 | </varlistentry> |
| 190 | <varlistentry> |
Philipp Zabel | 8cee396 | 2015-05-04 07:51:04 -0300 | [diff] [blame] | 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. |
Hans Verkuil | 9cae84b | 2015-05-15 07:28:02 -0300 | [diff] [blame] | 197 | </para> |
Philipp Zabel | 8cee396 | 2015-05-04 07:51:04 -0300 | [diff] [blame] | 198 | </listitem> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 199 | </varlistentry> |
| 200 | </variablelist> |
| 201 | </refsect1> |
| 202 | </refentry> |