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 the device buffers applications must initialize the
  66 relevant fields of the <structname>v4l2_create_buffers</structname> structure.
  67 The <structfield>count</structfield> field must be set to the number of
  68 requested buffers, the <structfield>memory</structfield> field specifies the
  69 requested I/O method and the <structfield>reserved</structfield> array must be
  70 zeroed.</para>
  71
  72     <para>The <structfield>format</structfield> field specifies the image format
  73 that the buffers must be able to handle. The application has to fill in this
  74 &v4l2-format;. Usually this will be done using the
  75 <constant>VIDIOC_TRY_FMT</constant> or <constant>VIDIOC_G_FMT</constant> ioctl()
  76 to ensure that the requested format is supported by the driver. Unsupported
  77 formats will result in an error.</para>
  78
  79     <para>The buffers created by this ioctl will have as minimum size the size
  80 defined by the <structfield>format.pix.sizeimage</structfield> field. If the
  81 <structfield>format.pix.sizeimage</structfield> field is less than the minimum
  82 required for the given format, then <structfield>sizeimage</structfield> will be
  83 increased by the driver to that minimum to allocate the buffers. If it is
  84 larger, then the value will be used as-is. The same applies to the
  85 <structfield>sizeimage</structfield> field of the
  86 <structname>v4l2_plane_pix_format</structname> structure in the case of
  87 multiplanar formats.</para>
  88
  89     <para>When the ioctl is called with a pointer to this structure the driver
  90 will attempt to allocate up to the requested number of buffers and store the
  91 actual number allocated and the starting index in the
  92 <structfield>count</structfield> and the <structfield>index</structfield> fields
  93 respectively. On return <structfield>count</structfield> can be smaller than
  94 the number requested. The driver may also increase buffer sizes if required,
  95 however, it will not update <structfield>sizeimage</structfield> field values.
  96 The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that
  97 information.</para>
  98
  99     <table pgwide="1" frame="none" id="v4l2-create-buffers">
 100       <title>struct <structname>v4l2_create_buffers</structname></title>
 101       <tgroup cols="3">
 102         &cs-str;
 103         <tbody valign="top">
 104           <row>
 105             <entry>__u32</entry>
 106             <entry><structfield>index</structfield></entry>
 107             <entry>The starting buffer index, returned by the driver.</entry>
 108           </row>
 109           <row>
 110             <entry>__u32</entry>
 111             <entry><structfield>count</structfield></entry>
 112             <entry>The number of buffers requested or granted. If count == 0, then
 113             <constant>VIDIOC_CREATE_BUFS</constant> will set <structfield>index</structfield>
 114             to the current number of created buffers, and it will check the validity of
 115             <structfield>memory</structfield> and <structfield>format.type</structfield>.
 116             If those are invalid -1 is returned and errno is set to &EINVAL;,
 117             otherwise <constant>VIDIOC_CREATE_BUFS</constant> returns 0. It will
 118             never set errno to &EBUSY; in this particular case.</entry>
 119           </row>
 120           <row>
 121             <entry>__u32</entry>
 122             <entry><structfield>memory</structfield></entry>
 123             <entry>Applications set this field to
 124 <constant>V4L2_MEMORY_MMAP</constant>,
 125 <constant>V4L2_MEMORY_DMABUF</constant> or
 126 <constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
 127 /></entry>
 128           </row>
 129           <row>
 130             <entry>&v4l2-format;</entry>
 131             <entry><structfield>format</structfield></entry>
 132             <entry>Filled in by the application, preserved by the driver.</entry>
 133           </row>
 134           <row>
 135             <entry>__u32</entry>
 136             <entry><structfield>reserved</structfield>[8]</entry>
 137             <entry>A place holder for future extensions. Drivers and applications
 138 must set the array to zero.</entry>
 139           </row>
 140         </tbody>
 141       </tgroup>
 142     </table>
 143   </refsect1>
 144
 145   <refsect1>
 146     &return-value;
 147
 148     <variablelist>
 149       <varlistentry>
 150         <term><errorcode>ENOMEM</errorcode></term>
 151         <listitem>
 152           <para>No memory to allocate buffers for <link linkend="mmap">memory
 153 mapped</link> I/O.</para>
 154         </listitem>
 155       </varlistentry>
 156       <varlistentry>
 157         <term><errorcode>EINVAL</errorcode></term>
 158         <listitem>
 159           <para>The buffer type (<structfield>format.type</structfield> field),
 160 requested I/O method (<structfield>memory</structfield>) or format
 161 (<structfield>format</structfield> field) is not valid.</para>
 162         </listitem>
 163       </varlistentry>
 164     </variablelist>
 165   </refsect1>
 166 </refentry>