About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / vidioc-create-bufs.xml




Custom Search

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

1	<refentry id="vidioc-create-bufs">
2	  <refmeta>
3	    <refentrytitle>ioctl VIDIOC_CREATE_BUFS</refentrytitle>
4	    &manvol;
5	  </refmeta>
6	
7	  <refnamediv>
8	    <refname>VIDIOC_CREATE_BUFS</refname>
9	    <refpurpose>Create buffers for Memory Mapped or User Pointer or DMA Buffer
10	    I/O</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_create_buffers *<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_CREATE_BUFS</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 used to create buffers for <link linkend="mmap">memory
53	mapped</link> or <link linkend="userp">user pointer</link> or <link
54	linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in
55	addition to the &VIDIOC-REQBUFS; ioctl, when a tighter
56	control over buffers is required. This ioctl can be called multiple times to
57	create buffers of different sizes.</para>
58	
59	    <para>To allocate the device buffers applications must initialize the
60	relevant fields of the <structname>v4l2_create_buffers</structname> structure.
61	The <structfield>count</structfield> field must be set to the number of
62	requested buffers, the <structfield>memory</structfield> field specifies the
63	requested I/O method and the <structfield>reserved</structfield> array must be
64	zeroed.</para>
65	
66	    <para>The <structfield>format</structfield> field specifies the image format
67	that the buffers must be able to handle. The application has to fill in this
68	&v4l2-format;. Usually this will be done using the &VIDIOC-TRY-FMT; or &VIDIOC-G-FMT; ioctls
69	to ensure that the requested format is supported by the driver.
70	Based on the format's <structfield>type</structfield> field the requested buffer
71	size (for single-planar) or plane sizes (for multi-planar formats) will be
72	used for the allocated buffers. The driver may return an error if the size(s)
73	are not supported by the hardware (usually because they are too small).</para>
74	
75	    <para>The buffers created by this ioctl will have as minimum size the size
76	defined by the <structfield>format.pix.sizeimage</structfield> field (or the
77	corresponding fields for other format types). Usually if the
78	<structfield>format.pix.sizeimage</structfield> field is less than the minimum
79	required for the given format, then an error will be returned since drivers will
80	typically not allow this. If it is larger, then the value will be used as-is.
81	In other words, the driver may reject the requested size, but if it is accepted
82	the driver will use it unchanged.</para>
83	
84	    <para>When the ioctl is called with a pointer to this structure the driver
85	will attempt to allocate up to the requested number of buffers and store the
86	actual number allocated and the starting index in the
87	<structfield>count</structfield> and the <structfield>index</structfield> fields
88	respectively. On return <structfield>count</structfield> can be smaller than
89	the number requested.</para>
90	
91	    <table pgwide="1" frame="none" id="v4l2-create-buffers">
92	      <title>struct <structname>v4l2_create_buffers</structname></title>
93	      <tgroup cols="3">
94		&cs-str;
95		<tbody valign="top">
96		  <row>
97		    <entry>__u32</entry>
98		    <entry><structfield>index</structfield></entry>
99		    <entry>The starting buffer index, returned by the driver.</entry>
100		  </row>
101		  <row>
102		    <entry>__u32</entry>
103		    <entry><structfield>count</structfield></entry>
104		    <entry>The number of buffers requested or granted. If count == 0, then
105		    <constant>VIDIOC_CREATE_BUFS</constant> will set <structfield>index</structfield>
106		    to the current number of created buffers, and it will check the validity of
107		    <structfield>memory</structfield> and <structfield>format.type</structfield>.
108		    If those are invalid -1 is returned and errno is set to &EINVAL;,
109		    otherwise <constant>VIDIOC_CREATE_BUFS</constant> returns 0. It will
110		    never set errno to &EBUSY; in this particular case.</entry>
111		  </row>
112		  <row>
113		    <entry>__u32</entry>
114		    <entry><structfield>memory</structfield></entry>
115		    <entry>Applications set this field to
116	<constant>V4L2_MEMORY_MMAP</constant>,
117	<constant>V4L2_MEMORY_DMABUF</constant> or
118	<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
119	/></entry>
120		  </row>
121		  <row>
122		    <entry>&v4l2-format;</entry>
123		    <entry><structfield>format</structfield></entry>
124		    <entry>Filled in by the application, preserved by the driver.</entry>
125		  </row>
126		  <row>
127		    <entry>__u32</entry>
128		    <entry><structfield>reserved</structfield>[8]</entry>
129		    <entry>A place holder for future extensions. Drivers and applications
130	must set the array to zero.</entry>
131		  </row>
132		</tbody>
133	      </tgroup>
134	    </table>
135	  </refsect1>
136	
137	  <refsect1>
138	    &return-value;
139	
140	    <variablelist>
141	      <varlistentry>
142		<term><errorcode>ENOMEM</errorcode></term>
143		<listitem>
144		  <para>No memory to allocate buffers for <link linkend="mmap">memory
145	mapped</link> I/O.</para>
146		</listitem>
147	      </varlistentry>
148	      <varlistentry>
149		<term><errorcode>EINVAL</errorcode></term>
150		<listitem>
151		  <para>The buffer type (<structfield>format.type</structfield> field),
152	requested I/O method (<structfield>memory</structfield>) or format
153	(<structfield>format</structfield> field) is not valid.</para>
154		</listitem>
155	      </varlistentry>
156	    </variablelist>
157	  </refsect1>
158	</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.