blob: cd9943672434e29b629bf5a46e5aa42749008171 [file] [log] [blame]
Guennadi Liakhovetski55093282011-09-28 08:10:58 -03001<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>
Tomasz Stanislawski4b9c1cb2012-06-14 10:37:36 -03009 <refpurpose>Create buffers for Memory Mapped or User Pointer or DMA Buffer
10 I/O</refpurpose>
Guennadi Liakhovetski55093282011-09-28 08:10:58 -030011 </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
Hans Verkuil7dcc6062012-05-15 08:04:28 -030052 <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
Guennadi Liakhovetski55093282011-09-28 08:10:58 -030058 <para>This ioctl is used to create buffers for <link linkend="mmap">memory
Tomasz Stanislawski4b9c1cb2012-06-14 10:37:36 -030059mapped</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>
Guennadi Liakhovetski55093282011-09-28 08:10:58 -030064
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
Nicolas THERY6992c082012-07-18 11:41:36 -030068&v4l2-format; structure, embedded in this
Guennadi Liakhovetski55093282011-09-28 08:10:58 -030069structure, 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>
Hans Verkuil5d44f5e2012-06-22 05:47:30 -0300101 <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>
Guennadi Liakhovetski55093282011-09-28 08:10:58 -0300108 </row>
109 <row>
Sakari Ailus6016af82012-05-10 02:02:07 -0300110 <entry>__u32</entry>
Guennadi Liakhovetski55093282011-09-28 08:10:58 -0300111 <entry><structfield>memory</structfield></entry>
112 <entry>Applications set this field to
Tomasz Stanislawski4b9c1cb2012-06-14 10:37:36 -0300113<constant>V4L2_MEMORY_MMAP</constant>,
114<constant>V4L2_MEMORY_DMABUF</constant> or
Sakari Ailus6016af82012-05-10 02:02:07 -0300115<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
116/></entry>
Guennadi Liakhovetski55093282011-09-28 08:10:58 -0300117 </row>
118 <row>
Nicolas THERY6992c082012-07-18 11:41:36 -0300119 <entry>&v4l2-format;</entry>
Guennadi Liakhovetski55093282011-09-28 08:10:58 -0300120 <entry><structfield>format</structfield></entry>
Sakari Ailusaf038912012-05-31 18:51:05 -0300121 <entry>Filled in by the application, preserved by the driver.</entry>
Guennadi Liakhovetski55093282011-09-28 08:10:58 -0300122 </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>