Documentation/DocBook/media/v4l/vidioc-create-bufs.xml

   1 <refentry id="vidioc-create-bufs">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_CREATE_BUFS</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_CREATE_BUFS</refname>
   9     <refpurpose>Create buffers for Memory Mapped 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_create_buffers *<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_CREATE_BUFS</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 create buffers for <link linkend="mmap">memory
  52 mapped</link> or <link linkend="userp">user pointer</link>
  53 I/O. It can be used as an alternative or in addition to the
  54 <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter control over buffers
  55 is required. This ioctl can be called multiple times to create buffers of
  56 different sizes.</para>
  57
  58     <para>To allocate device buffers applications initialize relevant fields of
  59 the <structname>v4l2_create_buffers</structname> structure. They set the
  60 <structfield>type</structfield> field in the
  61 <structname>v4l2_format</structname> structure, embedded in this
  62 structure, to the respective stream or buffer type.
  63 <structfield>count</structfield> must be set to the number of required buffers.
  64 <structfield>memory</structfield> specifies the required I/O method. The
  65 <structfield>format</structfield> field shall typically be filled in using
  66 either the <constant>VIDIOC_TRY_FMT</constant> or
  67 <constant>VIDIOC_G_FMT</constant> ioctl(). Additionally, applications can adjust
  68 <structfield>sizeimage</structfield> fields to fit their specific needs. The
  69 <structfield>reserved</structfield> array must be zeroed.</para>
  70
  71     <para>When the ioctl is called with a pointer to this structure the driver
  72 will attempt to allocate up to the requested number of buffers and store the
  73 actual number allocated and the starting index in the
  74 <structfield>count</structfield> and the <structfield>index</structfield> fields
  75 respectively. On return <structfield>count</structfield> can be smaller than
  76 the number requested. The driver may also increase buffer sizes if required,
  77 however, it will not update <structfield>sizeimage</structfield> field values.
  78 The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that
  79 information.</para>
  80
  81     <table pgwide="1" frame="none" id="v4l2-create-buffers">
  82       <title>struct <structname>v4l2_create_buffers</structname></title>
  83       <tgroup cols="3">
  84         &cs-str;
  85         <tbody valign="top">
  86           <row>
  87             <entry>__u32</entry>
  88             <entry><structfield>index</structfield></entry>
  89             <entry>The starting buffer index, returned by the driver.</entry>
  90           </row>
  91           <row>
  92             <entry>__u32</entry>
  93             <entry><structfield>count</structfield></entry>
  94             <entry>The number of buffers requested or granted.</entry>
  95           </row>
  96           <row>
  97             <entry>&v4l2-memory;</entry>
  98             <entry><structfield>memory</structfield></entry>
  99             <entry>Applications set this field to
 100 <constant>V4L2_MEMORY_MMAP</constant> or
 101 <constant>V4L2_MEMORY_USERPTR</constant>.</entry>
 102           </row>
 103           <row>
 104             <entry>&v4l2-format;</entry>
 105             <entry><structfield>format</structfield></entry>
 106             <entry>Filled in by the application, preserved by the driver.</entry>
 107           </row>
 108           <row>
 109             <entry>__u32</entry>
 110             <entry><structfield>reserved</structfield>[8]</entry>
 111             <entry>A place holder for future extensions.</entry>
 112           </row>
 113         </tbody>
 114       </tgroup>
 115     </table>
 116   </refsect1>
 117
 118   <refsect1>
 119     &return-value;
 120
 121     <variablelist>
 122       <varlistentry>
 123         <term><errorcode>ENOMEM</errorcode></term>
 124         <listitem>
 125           <para>No memory to allocate buffers for <link linkend="mmap">memory
 126 mapped</link> I/O.</para>
 127         </listitem>
 128       </varlistentry>
 129       <varlistentry>
 130         <term><errorcode>EINVAL</errorcode></term>
 131         <listitem>
 132           <para>The buffer type (<structfield>type</structfield> field) or the
 133 requested I/O method (<structfield>memory</structfield>) is not
 134 supported.</para>
 135         </listitem>
 136       </varlistentry>
 137     </variablelist>
 138   </refsect1>
 139 </refentry>