About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / vidioc-expbuf.xml




Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.