About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:39 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	    <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.
76	Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, and O_RDWR are supported.  All
77	other fields must be set to zero.
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>
87	  </refsect1>
88	
89	  <refsect1>
90	    <title>Examples</title>
91	
92	    <example>
93	      <title>Exporting a buffer.</title>
94	      <programlisting>
95	int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd)
96	{
97		&v4l2-exportbuffer; expbuf;
98	
99		memset(&amp;expbuf, 0, sizeof(expbuf));
100		expbuf.type = bt;
101		expbuf.index = index;
102		if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;expbuf) == -1) {
103			perror("VIDIOC_EXPBUF");
104			return -1;
105		}
106	
107		*dmafd = expbuf.fd;
108	
109		return 0;
110	}
111	      </programlisting>
112	    </example>
113	
114	    <example>
115	      <title>Exporting a buffer using the multi-planar API.</title>
116	      <programlisting>
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 &lt; n_planes; ++i) {
123			&v4l2-exportbuffer; expbuf;
124	
125			memset(&amp;expbuf, 0, sizeof(expbuf));
126			expbuf.type = bt;
127			expbuf.index = index;
128			expbuf.plane = i;
129			if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;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	}
140	      </programlisting>
141	    </example>
142	
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>
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>
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>
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.