1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
<refentry id="vidioc-create-bufs">
<refmeta>
<refentrytitle>ioctl VIDIOC_CREATE_BUFS</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_CREATE_BUFS</refname>
<refpurpose>Create buffers for Memory Mapped or User Pointer or DMA Buffer
I/O</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_create_buffers *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_CREATE_BUFS</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<note>
<title>Experimental</title>
<para>This is an <link linkend="experimental"> experimental </link>
interface and may change in the future.</para>
</note>
<para>This ioctl is used to create buffers for <link linkend="mmap">memory
mapped</link> or <link linkend="userp">user pointer</link> or <link
linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in
addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter
control over buffers is required. This ioctl can be called multiple times to
create buffers of different sizes.</para>
<para>To allocate the device buffers applications must initialize the
relevant fields of the <structname>v4l2_create_buffers</structname> structure.
The <structfield>count</structfield> field must be set to the number of
requested buffers, the <structfield>memory</structfield> field specifies the
requested I/O method and the <structfield>reserved</structfield> array must be
zeroed.</para>
<para>The <structfield>format</structfield> field specifies the image format
that the buffers must be able to handle. The application has to fill in this
&v4l2-format;. Usually this will be done using the
<constant>VIDIOC_TRY_FMT</constant> or <constant>VIDIOC_G_FMT</constant> ioctl()
to ensure that the requested format is supported by the driver. Unsupported
formats will result in an error.</para>
<para>The buffers created by this ioctl will have as minimum size the size
defined by the <structfield>format.pix.sizeimage</structfield> field. If the
<structfield>format.pix.sizeimage</structfield> field is less than the minimum
required for the given format, then <structfield>sizeimage</structfield> will be
increased by the driver to that minimum to allocate the buffers. If it is
larger, then the value will be used as-is. The same applies to the
<structfield>sizeimage</structfield> field of the
<structname>v4l2_plane_pix_format</structname> structure in the case of
multiplanar formats.</para>
<para>When the ioctl is called with a pointer to this structure the driver
will attempt to allocate up to the requested number of buffers and store the
actual number allocated and the starting index in the
<structfield>count</structfield> and the <structfield>index</structfield> fields
respectively. On return <structfield>count</structfield> can be smaller than
the number requested. The driver may also increase buffer sizes if required,
however, it will not update <structfield>sizeimage</structfield> field values.
The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that
information.</para>
<table pgwide="1" frame="none" id="v4l2-create-buffers">
<title>struct <structname>v4l2_create_buffers</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>The starting buffer index, returned by the driver.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>count</structfield></entry>
<entry>The number of buffers requested or granted. If count == 0, then
<constant>VIDIOC_CREATE_BUFS</constant> will set <structfield>index</structfield>
to the current number of created buffers, and it will check the validity of
<structfield>memory</structfield> and <structfield>format.type</structfield>.
If those are invalid -1 is returned and errno is set to &EINVAL;,
otherwise <constant>VIDIOC_CREATE_BUFS</constant> returns 0. It will
never set errno to &EBUSY; in this particular case.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>memory</structfield></entry>
<entry>Applications set this field to
<constant>V4L2_MEMORY_MMAP</constant>,
<constant>V4L2_MEMORY_DMABUF</constant> or
<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
/></entry>
</row>
<row>
<entry>&v4l2-format;</entry>
<entry><structfield>format</structfield></entry>
<entry>Filled in by the application, preserved by the driver.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[8]</entry>
<entry>A place holder for future extensions. Drivers and applications
must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>ENOMEM</errorcode></term>
<listitem>
<para>No memory to allocate buffers for <link linkend="mmap">memory
mapped</link> I/O.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The buffer type (<structfield>format.type</structfield> field),
requested I/O method (<structfield>memory</structfield>) or format
(<structfield>format</structfield> field) is not valid.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
|
