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