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
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
<refentry id="vidioc-expbuf">
<refmeta>
<refentrytitle>ioctl VIDIOC_EXPBUF</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_EXPBUF</refname>
<refpurpose>Export a buffer as a DMABUF file descriptor.</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_exportbuffer *<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_EXPBUF</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 an extension to the <link linkend="mmap">memory
mapping</link> I/O method, therefore it is available only for
<constant>V4L2_MEMORY_MMAP</constant> buffers. It can be used to export a
buffer as a DMABUF file at any time after buffers have been allocated with the
&VIDIOC-REQBUFS; ioctl.</para>
<para> To export a buffer, applications fill &v4l2-exportbuffer;. The
<structfield>type</structfield> field is set to the same buffer type as was
previously used with &v4l2-requestbuffers; <structfield>type</structfield>.
Applications must also set the <structfield>index</structfield> field. Valid
index numbers range from zero to the number of buffers allocated with
&VIDIOC-REQBUFS; (&v4l2-requestbuffers; <structfield>count</structfield>)
minus one. For the multi-planar API, applications set the <structfield>plane</structfield>
field to the index of the plane to be exported. Valid planes
range from zero to the maximal number of valid planes for the currently active
format. For the single-planar API, applications must set <structfield>plane</structfield>
to zero. Additional flags may be posted in the <structfield>flags</structfield>
field. Refer to a manual for open() for details.
Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, and O_RDWR are supported. All
other fields must be set to zero.
In the case of multi-planar API, every plane is exported separately using
multiple <constant>VIDIOC_EXPBUF</constant> calls.</para>
<para>After calling <constant>VIDIOC_EXPBUF</constant> the <structfield>fd</structfield>
field will be set by a driver. This is a DMABUF file
descriptor. The application may pass it to other DMABUF-aware devices. Refer to
<link linkend="dmabuf">DMABUF importing</link> for details about importing
DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it
is no longer used to allow the associated memory to be reclaimed.</para>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Exporting a buffer.</title>
<programlisting>
int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd)
{
&v4l2-exportbuffer; expbuf;
memset(&expbuf, 0, sizeof(expbuf));
expbuf.type = bt;
expbuf.index = index;
if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) {
perror("VIDIOC_EXPBUF");
return -1;
}
*dmafd = expbuf.fd;
return 0;
}
</programlisting>
</example>
<example>
<title>Exporting a buffer using the multi-planar API.</title>
<programlisting>
int buffer_export_mp(int v4lfd, &v4l2-buf-type; bt, int index,
int dmafd[], int n_planes)
{
int i;
for (i = 0; i < n_planes; ++i) {
&v4l2-exportbuffer; expbuf;
memset(&expbuf, 0, sizeof(expbuf));
expbuf.type = bt;
expbuf.index = index;
expbuf.plane = i;
if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) {
perror("VIDIOC_EXPBUF");
while (i)
close(dmafd[--i]);
return -1;
}
dmafd[i] = expbuf.fd;
}
return 0;
}
</programlisting>
</example>
<table pgwide="1" frame="none" id="v4l2-exportbuffer">
<title>struct <structname>v4l2_exportbuffer</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry>Type of the buffer, same as &v4l2-format;
<structfield>type</structfield> or &v4l2-requestbuffers;
<structfield>type</structfield>, set by the application. See <xref
linkend="v4l2-buf-type" /></entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>index</structfield></entry>
<entry>Number of the buffer, set by the application. This field is
only used for <link linkend="mmap">memory mapping</link> I/O and can range from
zero to the number of buffers allocated with the &VIDIOC-REQBUFS; and/or
&VIDIOC-CREATE-BUFS; ioctls. </entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>plane</structfield></entry>
<entry>Index of the plane to be exported when using the
multi-planar API. Otherwise this value must be set to zero. </entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>Flags for the newly created file, currently only
<constant>O_CLOEXEC</constant>, <constant>O_RDONLY</constant>, <constant>O_WRONLY</constant>,
and <constant>O_RDWR</constant> are supported, refer to the manual
of open() for more details.</entry>
</row>
<row>
<entry>__s32</entry>
<entry><structfield>fd</structfield></entry>
<entry>The DMABUF file descriptor associated with a buffer. Set by
the driver.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved[11]</structfield></entry>
<entry>Reserved field for future use. Drivers and applications must
set the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>A queue is not in MMAP mode or DMABUF exporting is not
supported or <structfield>flags</structfield> or <structfield>type</structfield>
or <structfield>index</structfield> or <structfield>plane</structfield> fields
are invalid.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
|
