Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.
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>
