Documentation/DocBook/v4l/vidioc-reqbufs.xml

   1 <refentry id="vidioc-reqbufs">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_REQBUFS</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_REQBUFS</refname>
   9     <refpurpose>Initiate Memory Mapping or User Pointer I/O</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcprototype>
  15         <funcdef>int <function>ioctl</function></funcdef>
  16         <paramdef>int <parameter>fd</parameter></paramdef>
  17         <paramdef>int <parameter>request</parameter></paramdef>
  18         <paramdef>struct v4l2_requestbuffers *<parameter>argp</parameter></paramdef>
  19       </funcprototype>
  20     </funcsynopsis>
  21   </refsynopsisdiv>
  22
  23   <refsect1>
  24     <title>Arguments</title>
  25
  26     <variablelist>
  27       <varlistentry>
  28         <term><parameter>fd</parameter></term>
  29         <listitem>
  30           <para>&fd;</para>
  31         </listitem>
  32       </varlistentry>
  33       <varlistentry>
  34         <term><parameter>request</parameter></term>
  35         <listitem>
  36           <para>VIDIOC_REQBUFS</para>
  37         </listitem>
  38       </varlistentry>
  39       <varlistentry>
  40         <term><parameter>argp</parameter></term>
  41         <listitem>
  42           <para></para>
  43         </listitem>
  44       </varlistentry>
  45     </variablelist>
  46   </refsect1>
  47
  48   <refsect1>
  49     <title>Description</title>
  50
  51     <para>This ioctl is used to initiate <link linkend="mmap">memory
  52 mapped</link> or <link linkend="userp">user pointer</link>
  53 I/O. Memory mapped buffers are located in device memory and must be
  54 allocated with this ioctl before they can be mapped into the
  55 application's address space. User buffers are allocated by
  56 applications themselves, and this ioctl is merely used to switch the
  57 driver into user pointer I/O mode.</para>
  58
  59     <para>To allocate device buffers applications initialize three
  60 fields of a <structname>v4l2_requestbuffers</structname> structure.
  61 They set the <structfield>type</structfield> field to the respective
  62 stream or buffer type, the <structfield>count</structfield> field to
  63 the desired number of buffers, and <structfield>memory</structfield>
  64 must be set to <constant>V4L2_MEMORY_MMAP</constant>. When the ioctl
  65 is called with a pointer to this structure the driver attempts to
  66 allocate the requested number of buffers and stores the actual number
  67 allocated in the <structfield>count</structfield> field. It can be
  68 smaller than the number requested, even zero, when the driver runs out
  69 of free memory. A larger number is possible when the driver requires
  70 more buffers to function correctly.<footnote>
  71         <para>For example video output requires at least two buffers,
  72 one displayed and one filled by the application.</para>
  73         </footnote> When memory mapping I/O is not supported the ioctl
  74 returns an &EINVAL;.</para>
  75
  76     <para>Applications can call <constant>VIDIOC_REQBUFS</constant>
  77 again to change the number of buffers, however this cannot succeed
  78 when any buffers are still mapped. A <structfield>count</structfield>
  79 value of zero frees all buffers, after aborting or finishing any DMA
  80 in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no
  81 reason why munmap()ping one or even all buffers must imply
  82 streamoff.--></para>
  83
  84     <para>To negotiate user pointer I/O, applications initialize only
  85 the <structfield>type</structfield> field and set
  86 <structfield>memory</structfield> to
  87 <constant>V4L2_MEMORY_USERPTR</constant>. When the ioctl is called
  88 with a pointer to this structure the driver prepares for user pointer
  89 I/O, when this I/O method is not supported the ioctl returns an
  90 &EINVAL;.</para>
  91
  92     <table pgwide="1" frame="none" id="v4l2-requestbuffers">
  93       <title>struct <structname>v4l2_requestbuffers</structname></title>
  94       <tgroup cols="3">
  95         &cs-str;
  96         <tbody valign="top">
  97           <row>
  98             <entry>__u32</entry>
  99             <entry><structfield>count</structfield></entry>
 100             <entry>The number of buffers requested or granted. This
 101 field is only used when <structfield>memory</structfield> is set to
 102 <constant>V4L2_MEMORY_MMAP</constant>.</entry>
 103           </row>
 104           <row>
 105             <entry>&v4l2-buf-type;</entry>
 106             <entry><structfield>type</structfield></entry>
 107             <entry>Type of the stream or buffers, this is the same
 108 as the &v4l2-format; <structfield>type</structfield> field. See <xref
 109                 linkend="v4l2-buf-type" /> for valid values.</entry>
 110           </row>
 111           <row>
 112             <entry>&v4l2-memory;</entry>
 113             <entry><structfield>memory</structfield></entry>
 114             <entry>Applications set this field to
 115 <constant>V4L2_MEMORY_MMAP</constant> or
 116 <constant>V4L2_MEMORY_USERPTR</constant>.</entry>
 117           </row>
 118           <row>
 119             <entry>__u32</entry>
 120             <entry><structfield>reserved</structfield>[2]</entry>
 121             <entry>A place holder for future extensions and custom
 122 (driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and
 123 higher.</entry>
 124           </row>
 125         </tbody>
 126       </tgroup>
 127     </table>
 128   </refsect1>
 129
 130   <refsect1>
 131     &return-value;
 132
 133     <variablelist>
 134       <varlistentry>
 135         <term><errorcode>EBUSY</errorcode></term>
 136         <listitem>
 137           <para>The driver supports multiple opens and I/O is already
 138 in progress, or reallocation of buffers was attempted although one or
 139 more are still mapped.</para>
 140         </listitem>
 141       </varlistentry>
 142       <varlistentry>
 143         <term><errorcode>EINVAL</errorcode></term>
 144         <listitem>
 145           <para>The buffer type (<structfield>type</structfield> field) or the
 146 requested I/O method (<structfield>memory</structfield>) is not
 147 supported.</para>
 148         </listitem>
 149       </varlistentry>
 150     </variablelist>
 151   </refsect1>
 152 </refentry>
 153
 154 <!--
 155 Local Variables:
 156 mode: sgml
 157 sgml-parent-document: "v4l2.sgml"
 158 indent-tabs-mode: nil
 159 End:
 160 -->