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

   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         <term><errorcode>EIO</errorcode></term>
 162         <listitem>
 163           <para><constant>VIDIOC_DQBUF</constant> failed due to an
 164 internal error. Can also indicate temporary problems like signal
 165 loss. Note the driver might dequeue an (empty) buffer despite
 166 returning an error, or even stop capturing. Reusing such buffer may be unsafe
 167 though and its details (e.g. <structfield>index</structfield>) may not be
 168 returned either. It is recommended that drivers indicate recoverable errors
 169 by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead.
 170 In that case the application should be able to safely reuse the buffer and
 171 continue streaming.
 172         </para>
 173         </listitem>
 174       </varlistentry>
 175     </variablelist>
 176   </refsect1>
 177 </refentry>