Merge branch 'master' of git://git.kernel.org/pub/scm/linux/kernel/git/jesse/openvswitch
[firefly-linux-kernel-4.4.55.git] / 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 I/O</refpurpose>
10   </refnamediv>
11
12   <refsynopsisdiv>
13     <funcsynopsis>
14       <funcprototype>
15         <funcdef>int <function>ioctl</function></funcdef>
16         <paramdef>int <parameter>fd</parameter></paramdef>
17         <paramdef>int <parameter>request</parameter></paramdef>
18         <paramdef>struct v4l2_create_buffers *<parameter>argp</parameter></paramdef>
19       </funcprototype>
20     </funcsynopsis>
21   </refsynopsisdiv>
22
23   <refsect1>
24     <title>Arguments</title>
25
26     <variablelist>
27       <varlistentry>
28         <term><parameter>fd</parameter></term>
29         <listitem>
30           <para>&fd;</para>
31         </listitem>
32       </varlistentry>
33       <varlistentry>
34         <term><parameter>request</parameter></term>
35         <listitem>
36           <para>VIDIOC_CREATE_BUFS</para>
37         </listitem>
38       </varlistentry>
39       <varlistentry>
40         <term><parameter>argp</parameter></term>
41         <listitem>
42           <para></para>
43         </listitem>
44       </varlistentry>
45     </variablelist>
46   </refsect1>
47
48   <refsect1>
49     <title>Description</title>
50
51     <note>
52       <title>Experimental</title>
53       <para>This is an <link linkend="experimental"> experimental </link>
54       interface and may change in the future.</para>
55     </note>
56
57     <para>This ioctl is used to create buffers for <link linkend="mmap">memory
58 mapped</link> or <link linkend="userp">user pointer</link>
59 I/O. It can be used as an alternative or in addition to the
60 <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter control over buffers
61 is required. This ioctl can be called multiple times to create buffers of
62 different sizes.</para>
63
64     <para>To allocate device buffers applications initialize relevant fields of
65 the <structname>v4l2_create_buffers</structname> structure. They set the
66 <structfield>type</structfield> field in the
67 <structname>v4l2_format</structname> structure, embedded in this
68 structure, to the respective stream or buffer type.
69 <structfield>count</structfield> must be set to the number of required buffers.
70 <structfield>memory</structfield> specifies the required I/O method. The
71 <structfield>format</structfield> field shall typically be filled in using
72 either the <constant>VIDIOC_TRY_FMT</constant> or
73 <constant>VIDIOC_G_FMT</constant> ioctl(). Additionally, applications can adjust
74 <structfield>sizeimage</structfield> fields to fit their specific needs. The
75 <structfield>reserved</structfield> array must be zeroed.</para>
76
77     <para>When the ioctl is called with a pointer to this structure the driver
78 will attempt to allocate up to the requested number of buffers and store the
79 actual number allocated and the starting index in the
80 <structfield>count</structfield> and the <structfield>index</structfield> fields
81 respectively. On return <structfield>count</structfield> can be smaller than
82 the number requested. The driver may also increase buffer sizes if required,
83 however, it will not update <structfield>sizeimage</structfield> field values.
84 The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that
85 information.</para>
86
87     <table pgwide="1" frame="none" id="v4l2-create-buffers">
88       <title>struct <structname>v4l2_create_buffers</structname></title>
89       <tgroup cols="3">
90         &cs-str;
91         <tbody valign="top">
92           <row>
93             <entry>__u32</entry>
94             <entry><structfield>index</structfield></entry>
95             <entry>The starting buffer index, returned by the driver.</entry>
96           </row>
97           <row>
98             <entry>__u32</entry>
99             <entry><structfield>count</structfield></entry>
100             <entry>The number of buffers requested or granted.</entry>
101           </row>
102           <row>
103             <entry>__u32</entry>
104             <entry><structfield>memory</structfield></entry>
105             <entry>Applications set this field to
106 <constant>V4L2_MEMORY_MMAP</constant> or
107 <constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
108 /></entry>
109           </row>
110           <row>
111             <entry>struct&nbsp;v4l2_format</entry>
112             <entry><structfield>format</structfield></entry>
113             <entry>Filled in by the application, preserved by the driver.</entry>
114           </row>
115           <row>
116             <entry>__u32</entry>
117             <entry><structfield>reserved</structfield>[8]</entry>
118             <entry>A place holder for future extensions.</entry>
119           </row>
120         </tbody>
121       </tgroup>
122     </table>
123   </refsect1>
124
125   <refsect1>
126     &return-value;
127
128     <variablelist>
129       <varlistentry>
130         <term><errorcode>ENOMEM</errorcode></term>
131         <listitem>
132           <para>No memory to allocate buffers for <link linkend="mmap">memory
133 mapped</link> I/O.</para>
134         </listitem>
135       </varlistentry>
136       <varlistentry>
137         <term><errorcode>EINVAL</errorcode></term>
138         <listitem>
139           <para>The buffer type (<structfield>type</structfield> field) or the
140 requested I/O method (<structfield>memory</structfield>) is not
141 supported.</para>
142         </listitem>
143       </varlistentry>
144     </variablelist>
145   </refsect1>
146 </refentry>