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 59mapped</link> or <link linkend="userp">user pointer</link> or <link 60linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in 61addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter 62control over buffers is required. This ioctl can be called multiple times to 63create buffers of different sizes.</para> 64 65 <para>To allocate device buffers applications initialize relevant fields of 66the <structname>v4l2_create_buffers</structname> structure. They set the 67<structfield>type</structfield> field in the 68&v4l2-format; structure, embedded in this 69structure, 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 73either 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 79will attempt to allocate up to the requested number of buffers and store the 80actual number allocated and the starting index in the 81<structfield>count</structfield> and the <structfield>index</structfield> fields 82respectively. On return <structfield>count</structfield> can be smaller than 83the number requested. The driver may also increase buffer sizes if required, 84however, it will not update <structfield>sizeimage</structfield> field values. 85The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that 86information.</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 141mapped</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 148requested I/O method (<structfield>memory</structfield>) is not 149supported.</para> 150 </listitem> 151 </varlistentry> 152 </variablelist> 153 </refsect1> 154</refentry> 155