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     <para>This ioctl is used to create buffers for <link linkend="mmap">memory
  53 mapped</link> or <link linkend="userp">user pointer</link> or <link
  54 linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in
  55 addition to the &VIDIOC-REQBUFS; ioctl, when a tighter
  56 control over buffers is required. This ioctl can be called multiple times to
  57 create buffers of different sizes.</para>
  58
  59     <para>To allocate the device buffers applications must initialize the
  60 relevant fields of the <structname>v4l2_create_buffers</structname> structure.
  61 The <structfield>count</structfield> field must be set to the number of
  62 requested buffers, the <structfield>memory</structfield> field specifies the
  63 requested I/O method and the <structfield>reserved</structfield> array must be
  64 zeroed.</para>
  65
  66     <para>The <structfield>format</structfield> field specifies the image format
  67 that the buffers must be able to handle. The application has to fill in this
  68 &v4l2-format;. Usually this will be done using the &VIDIOC-TRY-FMT; or &VIDIOC-G-FMT; ioctls
  69 to ensure that the requested format is supported by the driver.
  70 Based on the format's <structfield>type</structfield> field the requested buffer
  71 size (for single-planar) or plane sizes (for multi-planar formats) will be
  72 used for the allocated buffers. The driver may return an error if the size(s)
  73 are not supported by the hardware (usually because they are too small).</para>
  74
  75     <para>The buffers created by this ioctl will have as minimum size the size
  76 defined by the <structfield>format.pix.sizeimage</structfield> field (or the
  77 corresponding fields for other format types). Usually if the
  78 <structfield>format.pix.sizeimage</structfield> field is less than the minimum
  79 required for the given format, then an error will be returned since drivers will
  80 typically not allow this. If it is larger, then the value will be used as-is.
  81 In other words, the driver may reject the requested size, but if it is accepted
  82 the driver will use it unchanged.</para>
  83
  84     <para>When the ioctl is called with a pointer to this structure the driver
  85 will attempt to allocate up to the requested number of buffers and store the
  86 actual number allocated and the starting index in the
  87 <structfield>count</structfield> and the <structfield>index</structfield> fields
  88 respectively. On return <structfield>count</structfield> can be smaller than
  89 the number requested.</para>
  90
  91     <table pgwide="1" frame="none" id="v4l2-create-buffers">
  92       <title>struct <structname>v4l2_create_buffers</structname></title>
  93       <tgroup cols="3">
  94         &cs-str;
  95         <tbody valign="top">
  96           <row>
  97             <entry>__u32</entry>
  98             <entry><structfield>index</structfield></entry>
  99             <entry>The starting buffer index, returned by the driver.</entry>
 100           </row>
 101           <row>
 102             <entry>__u32</entry>
 103             <entry><structfield>count</structfield></entry>
 104             <entry>The number of buffers requested or granted. If count == 0, then
 105             <constant>VIDIOC_CREATE_BUFS</constant> will set <structfield>index</structfield>
 106             to the current number of created buffers, and it will check the validity of
 107             <structfield>memory</structfield> and <structfield>format.type</structfield>.
 108             If those are invalid -1 is returned and errno is set to &EINVAL;,
 109             otherwise <constant>VIDIOC_CREATE_BUFS</constant> returns 0. It will
 110             never set errno to &EBUSY; in this particular case.</entry>
 111           </row>
 112           <row>
 113             <entry>__u32</entry>
 114             <entry><structfield>memory</structfield></entry>
 115             <entry>Applications set this field to
 116 <constant>V4L2_MEMORY_MMAP</constant>,
 117 <constant>V4L2_MEMORY_DMABUF</constant> or
 118 <constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
 119 /></entry>
 120           </row>
 121           <row>
 122             <entry>&v4l2-format;</entry>
 123             <entry><structfield>format</structfield></entry>
 124             <entry>Filled in by the application, preserved by the driver.</entry>
 125           </row>
 126           <row>
 127             <entry>__u32</entry>
 128             <entry><structfield>reserved</structfield>[8]</entry>
 129             <entry>A place holder for future extensions. Drivers and applications
 130 must set the array to zero.</entry>
 131           </row>
 132         </tbody>
 133       </tgroup>
 134     </table>
 135   </refsect1>
 136
 137   <refsect1>
 138     &return-value;
 139
 140     <variablelist>
 141       <varlistentry>
 142         <term><errorcode>ENOMEM</errorcode></term>
 143         <listitem>
 144           <para>No memory to allocate buffers for <link linkend="mmap">memory
 145 mapped</link> I/O.</para>
 146         </listitem>
 147       </varlistentry>
 148       <varlistentry>
 149         <term><errorcode>EINVAL</errorcode></term>
 150         <listitem>
 151           <para>The buffer type (<structfield>format.type</structfield> field),
 152 requested I/O method (<structfield>memory</structfield>) or format
 153 (<structfield>format</structfield> field) is not valid.</para>
 154         </listitem>
 155       </varlistentry>
 156     </variablelist>
 157   </refsect1>
 158 </refentry>