Documentation/DocBook/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> or
  68 <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
  69 initialize the <structfield>bytesused</structfield>,
  70 <structfield>field</structfield> and
  71 <structfield>timestamp</structfield> fields, see <xref
  72 linkend="buffer" /> for details.
  73 Applications must also set <structfield>flags</structfield> to 0. If a driver
  74 supports capturing from specific video inputs and you want to specify a video
  75 input, 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.
  78 The <structfield>reserved</structfield> field must be set to 0.
  79 </para>
  80
  81     <para>To enqueue a <link linkend="mmap">memory mapped</link>
  82 buffer applications set the <structfield>memory</structfield>
  83 field to <constant>V4L2_MEMORY_MMAP</constant>. When
  84 <constant>VIDIOC_QBUF</constant> is called with a pointer to this
  85 structure 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>
  93 buffer applications set the <structfield>memory</structfield>
  94 field to <constant>V4L2_MEMORY_USERPTR</constant>, the
  95 <structfield>m.userptr</structfield> field to the address of the
  96 buffer and <structfield>length</structfield> to its size.
  97 When <constant>VIDIOC_QBUF</constant> is called with a pointer to this
  98 structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant>
  99 flag 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.
 102 This ioctl locks the memory pages of the buffer in physical memory,
 103 they cannot be swapped out to disk. Buffers remain locked until
 104 dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is
 105 called, or until the device is closed.</para>
 106
 107     <para>Applications call the <constant>VIDIOC_DQBUF</constant>
 108 ioctl to dequeue a filled (capturing) or displayed (output) buffer
 109 from the driver's outgoing queue. They just set the
 110 <structfield>type</structfield>, <structfield>memory</structfield>
 111 and <structfield>reserved</structfield>
 112 fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
 113 is called with a pointer to this structure the driver fills the
 114 remaining fields or returns an error code. The driver may also set
 115 <constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
 116 field. It indicates a non-critical (recoverable) streaming error. In such case
 117 the application may continue as normal, but should be aware that data in the
 118 dequeued buffer might be corrupted.</para>
 119
 120     <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
 121 buffer is in the outgoing queue. When the
 122 <constant>O_NONBLOCK</constant> flag was given to the &func-open;
 123 function, <constant>VIDIOC_DQBUF</constant> returns immediately
 124 with an &EAGAIN; when no buffer is available.</para>
 125
 126     <para>The <structname>v4l2_buffer</structname> structure is
 127 specified 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
 139 queue.</para>
 140         </listitem>
 141       </varlistentry>
 142       <varlistentry>
 143         <term><errorcode>EINVAL</errorcode></term>
 144         <listitem>
 145           <para>The buffer <structfield>type</structfield> is not
 146 supported, or the <structfield>index</structfield> is out of bounds,
 147 or 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
 156 enqueue 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
 163 internal error. Can also indicate temporary problems like signal
 164 loss. Note the driver might dequeue an (empty) buffer despite
 165 returning an error, or even stop capturing. Reusing such buffer may be unsafe
 166 though and its details (e.g. <structfield>index</structfield>) may not be
 167 returned either. It is recommended that drivers indicate recoverable errors
 168 by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead.
 169 In that case the application should be able to safely reuse the buffer and
 170 continue streaming.
 171         </para>
 172         </listitem>
 173       </varlistentry>
 174     </variablelist>
 175   </refsect1>
 176 </refentry>
 177
 178 <!--
 179 Local Variables:
 180 mode: sgml
 181 sgml-parent-document: "v4l2.sgml"
 182 indent-tabs-mode: nil
 183 End:
 184 -->