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 <link linkend="mmap">memory mapped</link>
  58 buffer applications set the <structfield>type</structfield> field of a
  59 &v4l2-buffer; to the same buffer type as previously &v4l2-format;
  60 <structfield>type</structfield> and &v4l2-requestbuffers;
  61 <structfield>type</structfield>, the <structfield>memory</structfield>
  62 field to <constant>V4L2_MEMORY_MMAP</constant> and the
  63 <structfield>index</structfield> field. Valid index numbers range from
  64 zero to the number of buffers allocated with &VIDIOC-REQBUFS;
  65 (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The
  66 contents of the struct <structname>v4l2_buffer</structname> returned
  67 by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is
  68 intended for output (<structfield>type</structfield> is
  69 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
  70 <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
  71 initialize the <structfield>bytesused</structfield>,
  72 <structfield>field</structfield> and
  73 <structfield>timestamp</structfield> fields. See <xref
  74         linkend="buffer" /> for details. When
  75 <constant>VIDIOC_QBUF</constant> is called with a pointer to this
  76 structure the driver sets the
  77 <constant>V4L2_BUF_FLAG_MAPPED</constant> and
  78 <constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the
  79 <constant>V4L2_BUF_FLAG_DONE</constant> flag in the
  80 <structfield>flags</structfield> field, or it returns an
  81 &EINVAL;.</para>
  82
  83     <para>To enqueue a <link linkend="userp">user pointer</link>
  84 buffer applications set the <structfield>type</structfield> field of a
  85 &v4l2-buffer; to the same buffer type as previously &v4l2-format;
  86 <structfield>type</structfield> and &v4l2-requestbuffers;
  87 <structfield>type</structfield>, the <structfield>memory</structfield>
  88 field to <constant>V4L2_MEMORY_USERPTR</constant> and the
  89 <structfield>m.userptr</structfield> field to the address of the
  90 buffer and <structfield>length</structfield> to its size. When the
  91 buffer is intended for output additional fields must be set as above.
  92 When <constant>VIDIOC_QBUF</constant> is called with a pointer to this
  93 structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant>
  94 flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and
  95 <constant>V4L2_BUF_FLAG_DONE</constant> flags in the
  96 <structfield>flags</structfield> field, or it returns an error code.
  97 This ioctl locks the memory pages of the buffer in physical memory,
  98 they cannot be swapped out to disk. Buffers remain locked until
  99 dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl are
 100 called, or until the device is closed.</para>
 101
 102     <para>Applications call the <constant>VIDIOC_DQBUF</constant>
 103 ioctl to dequeue a filled (capturing) or displayed (output) buffer
 104 from the driver's outgoing queue. They just set the
 105 <structfield>type</structfield> and <structfield>memory</structfield>
 106 fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
 107 is called with a pointer to this structure the driver fills the
 108 remaining fields or returns an error code.</para>
 109
 110     <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
 111 buffer is in the outgoing queue. When the
 112 <constant>O_NONBLOCK</constant> flag was given to the &func-open;
 113 function, <constant>VIDIOC_DQBUF</constant> returns immediately
 114 with an &EAGAIN; when no buffer is available.</para>
 115
 116     <para>The <structname>v4l2_buffer</structname> structure is
 117 specified in <xref linkend="buffer" />.</para>
 118   </refsect1>
 119
 120   <refsect1>
 121     &return-value;
 122
 123     <variablelist>
 124       <varlistentry>
 125         <term><errorcode>EAGAIN</errorcode></term>
 126         <listitem>
 127           <para>Non-blocking I/O has been selected using
 128 <constant>O_NONBLOCK</constant> and no buffer was in the outgoing
 129 queue.</para>
 130         </listitem>
 131       </varlistentry>
 132       <varlistentry>
 133         <term><errorcode>EINVAL</errorcode></term>
 134         <listitem>
 135           <para>The buffer <structfield>type</structfield> is not
 136 supported, or the <structfield>index</structfield> is out of bounds,
 137 or no buffers have been allocated yet, or the
 138 <structfield>userptr</structfield> or
 139 <structfield>length</structfield> are invalid.</para>
 140         </listitem>
 141       </varlistentry>
 142       <varlistentry>
 143         <term><errorcode>ENOMEM</errorcode></term>
 144         <listitem>
 145           <para>Not enough physical or virtual memory was available to
 146 enqueue a user pointer buffer.</para>
 147         </listitem>
 148       </varlistentry>
 149       <varlistentry>
 150         <term><errorcode>EIO</errorcode></term>
 151         <listitem>
 152           <para><constant>VIDIOC_DQBUF</constant> failed due to an
 153 internal error. Can also indicate temporary problems like signal
 154 loss. Note the driver might dequeue an (empty) buffer despite
 155 returning an error, or even stop capturing.</para>
 156         </listitem>
 157       </varlistentry>
 158     </variablelist>
 159   </refsect1>
 160 </refentry>
 161
 162 <!--
 163 Local Variables:
 164 mode: sgml
 165 sgml-parent-document: "v4l2.sgml"
 166 indent-tabs-mode: nil
 167 End:
 168 -->