]>
Commit | Line | Data |
---|---|---|
19b6ef51 TS |
1 | <refentry id="vidioc-expbuf"> |
2 | ||
3 | <refmeta> | |
4 | <refentrytitle>ioctl VIDIOC_EXPBUF</refentrytitle> | |
5 | &manvol; | |
6 | </refmeta> | |
7 | ||
8 | <refnamediv> | |
9 | <refname>VIDIOC_EXPBUF</refname> | |
10 | <refpurpose>Export a buffer as a DMABUF file descriptor.</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_exportbuffer *<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_EXPBUF</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 | <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 | ||
58 | <para>This ioctl is an extension to the <link linkend="mmap">memory | |
59 | mapping</link> I/O method, therefore it is available only for | |
60 | <constant>V4L2_MEMORY_MMAP</constant> buffers. It can be used to export a | |
61 | buffer as a DMABUF file at any time after buffers have been allocated with the | |
62 | &VIDIOC-REQBUFS; ioctl.</para> | |
63 | ||
64 | <para> To export a buffer, applications fill &v4l2-exportbuffer;. The | |
65 | <structfield> type </structfield> field is set to the same buffer type as was | |
66 | previously used with &v4l2-requestbuffers;<structfield> type </structfield>. | |
67 | Applications must also set the <structfield> index </structfield> field. Valid | |
68 | index numbers range from zero to the number of buffers allocated with | |
69 | &VIDIOC-REQBUFS; (&v4l2-requestbuffers;<structfield> count </structfield>) | |
70 | minus one. For the multi-planar API, applications set the <structfield> plane | |
71 | </structfield> field to the index of the plane to be exported. Valid planes | |
72 | range from zero to the maximal number of valid planes for the currently active | |
73 | format. For the single-planar API, applications must set <structfield> plane | |
74 | </structfield> to zero. Additional flags may be posted in the <structfield> | |
75 | flags </structfield> field. Refer to a manual for open() for details. | |
c1b96a23 PZ |
76 | Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, and O_RDWR are supported. All |
77 | other fields must be set to zero. | |
19b6ef51 TS |
78 | In the case of multi-planar API, every plane is exported separately using |
79 | multiple <constant> VIDIOC_EXPBUF </constant> calls. </para> | |
80 | ||
81 | <para> After calling <constant>VIDIOC_EXPBUF</constant> the <structfield> fd | |
82 | </structfield> field will be set by a driver. This is a DMABUF file | |
83 | descriptor. The application may pass it to other DMABUF-aware devices. Refer to | |
84 | <link linkend="dmabuf">DMABUF importing</link> for details about importing | |
85 | DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it | |
86 | is no longer used to allow the associated memory to be reclaimed. </para> | |
19b6ef51 | 87 | </refsect1> |
07b64b83 | 88 | |
19b6ef51 | 89 | <refsect1> |
07b64b83 | 90 | <title>Examples</title> |
19b6ef51 | 91 | |
07b64b83 HV |
92 | <example> |
93 | <title>Exporting a buffer.</title> | |
94 | <programlisting> | |
19b6ef51 TS |
95 | int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd) |
96 | { | |
97 | &v4l2-exportbuffer; expbuf; | |
98 | ||
99 | memset(&expbuf, 0, sizeof(expbuf)); | |
100 | expbuf.type = bt; | |
101 | expbuf.index = index; | |
102 | if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { | |
103 | perror("VIDIOC_EXPBUF"); | |
104 | return -1; | |
105 | } | |
106 | ||
107 | *dmafd = expbuf.fd; | |
108 | ||
109 | return 0; | |
110 | } | |
07b64b83 HV |
111 | </programlisting> |
112 | </example> | |
19b6ef51 | 113 | |
07b64b83 HV |
114 | <example> |
115 | <title>Exporting a buffer using the multi-planar API.</title> | |
116 | <programlisting> | |
19b6ef51 TS |
117 | int buffer_export_mp(int v4lfd, &v4l2-buf-type; bt, int index, |
118 | int dmafd[], int n_planes) | |
119 | { | |
120 | int i; | |
121 | ||
122 | for (i = 0; i < n_planes; ++i) { | |
123 | &v4l2-exportbuffer; expbuf; | |
124 | ||
125 | memset(&expbuf, 0, sizeof(expbuf)); | |
126 | expbuf.type = bt; | |
127 | expbuf.index = index; | |
128 | expbuf.plane = i; | |
129 | if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { | |
130 | perror("VIDIOC_EXPBUF"); | |
131 | while (i) | |
132 | close(dmafd[--i]); | |
133 | return -1; | |
134 | } | |
135 | dmafd[i] = expbuf.fd; | |
136 | } | |
137 | ||
138 | return 0; | |
139 | } | |
07b64b83 HV |
140 | </programlisting> |
141 | </example> | |
19b6ef51 | 142 | |
19b6ef51 TS |
143 | <table pgwide="1" frame="none" id="v4l2-exportbuffer"> |
144 | <title>struct <structname>v4l2_exportbuffer</structname></title> | |
145 | <tgroup cols="3"> | |
146 | &cs-str; | |
147 | <tbody valign="top"> | |
148 | <row> | |
149 | <entry>__u32</entry> | |
150 | <entry><structfield>type</structfield></entry> | |
151 | <entry>Type of the buffer, same as &v4l2-format; | |
152 | <structfield>type</structfield> or &v4l2-requestbuffers; | |
153 | <structfield>type</structfield>, set by the application. See <xref | |
154 | linkend="v4l2-buf-type" /></entry> | |
155 | </row> | |
156 | <row> | |
157 | <entry>__u32</entry> | |
158 | <entry><structfield>index</structfield></entry> | |
159 | <entry>Number of the buffer, set by the application. This field is | |
160 | only used for <link linkend="mmap">memory mapping</link> I/O and can range from | |
161 | zero to the number of buffers allocated with the &VIDIOC-REQBUFS; and/or | |
162 | &VIDIOC-CREATE-BUFS; ioctls. </entry> | |
163 | </row> | |
164 | <row> | |
165 | <entry>__u32</entry> | |
166 | <entry><structfield>plane</structfield></entry> | |
167 | <entry>Index of the plane to be exported when using the | |
168 | multi-planar API. Otherwise this value must be set to zero. </entry> | |
169 | </row> | |
170 | <row> | |
171 | <entry>__u32</entry> | |
172 | <entry><structfield>flags</structfield></entry> | |
173 | <entry>Flags for the newly created file, currently only <constant> | |
c1b96a23 PZ |
174 | O_CLOEXEC </constant>, <constant>O_RDONLY</constant>, <constant>O_WRONLY |
175 | </constant>, and <constant>O_RDWR</constant> are supported, refer to the manual | |
176 | of open() for more details.</entry> | |
19b6ef51 TS |
177 | </row> |
178 | <row> | |
179 | <entry>__s32</entry> | |
180 | <entry><structfield>fd</structfield></entry> | |
181 | <entry>The DMABUF file descriptor associated with a buffer. Set by | |
182 | the driver.</entry> | |
183 | </row> | |
184 | <row> | |
185 | <entry>__u32</entry> | |
186 | <entry><structfield>reserved[11]</structfield></entry> | |
187 | <entry>Reserved field for future use. Must be set to zero.</entry> | |
188 | </row> | |
189 | </tbody> | |
190 | </tgroup> | |
191 | </table> | |
192 | ||
193 | </refsect1> | |
194 | ||
195 | <refsect1> | |
196 | &return-value; | |
197 | <variablelist> | |
198 | <varlistentry> | |
199 | <term><errorcode>EINVAL</errorcode></term> | |
200 | <listitem> | |
201 | <para>A queue is not in MMAP mode or DMABUF exporting is not | |
202 | supported or <structfield> flags </structfield> or <structfield> type | |
203 | </structfield> or <structfield> index </structfield> or <structfield> plane | |
204 | </structfield> fields are invalid.</para> | |
205 | </listitem> | |
206 | </varlistentry> | |
207 | </variablelist> | |
208 | </refsect1> | |
209 | ||
210 | </refentry> |