About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 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	    <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 used to create buffers for <link linkend="mmap">memory
59	mapped</link> or <link linkend="userp">user pointer</link> or <link
60	linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in
61	addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter
62	control over buffers is required. This ioctl can be called multiple times to
63	create buffers of different sizes.</para>
64	
65	    <para>To allocate the device buffers applications must initialize the
66	relevant fields of the <structname>v4l2_create_buffers</structname> structure.
67	The <structfield>count</structfield> field must be set to the number of
68	requested buffers, the <structfield>memory</structfield> field specifies the
69	requested I/O method and the <structfield>reserved</structfield> array must be
70	zeroed.</para>
71	
72	    <para>The <structfield>format</structfield> field specifies the image format
73	that the buffers must be able to handle. The application has to fill in this
74	&v4l2-format;. Usually this will be done using the
75	<constant>VIDIOC_TRY_FMT</constant> or <constant>VIDIOC_G_FMT</constant> ioctl()
76	to ensure that the requested format is supported by the driver. Unsupported
77	formats will result in an error.</para>
78	
79	    <para>The buffers created by this ioctl will have as minimum size the size
80	defined by the <structfield>format.pix.sizeimage</structfield> field. If the
81	<structfield>format.pix.sizeimage</structfield> field is less than the minimum
82	required for the given format, then <structfield>sizeimage</structfield> will be
83	increased by the driver to that minimum to allocate the buffers. If it is
84	larger, then the value will be used as-is. The same applies to the
85	<structfield>sizeimage</structfield> field of the
86	<structname>v4l2_plane_pix_format</structname> structure in the case of
87	multiplanar formats.</para>
88	
89	    <para>When the ioctl is called with a pointer to this structure the driver
90	will attempt to allocate up to the requested number of buffers and store the
91	actual number allocated and the starting index in the
92	<structfield>count</structfield> and the <structfield>index</structfield> fields
93	respectively. On return <structfield>count</structfield> can be smaller than
94	the number requested. The driver may also increase buffer sizes if required,
95	however, it will not update <structfield>sizeimage</structfield> field values.
96	The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that
97	information.</para>
98	
99	    <table pgwide="1" frame="none" id="v4l2-create-buffers">
100	      <title>struct <structname>v4l2_create_buffers</structname></title>
101	      <tgroup cols="3">
102		&cs-str;
103		<tbody valign="top">
104		  <row>
105		    <entry>__u32</entry>
106		    <entry><structfield>index</structfield></entry>
107		    <entry>The starting buffer index, returned by the driver.</entry>
108		  </row>
109		  <row>
110		    <entry>__u32</entry>
111		    <entry><structfield>count</structfield></entry>
112		    <entry>The number of buffers requested or granted. If count == 0, then
113		    <constant>VIDIOC_CREATE_BUFS</constant> will set <structfield>index</structfield>
114		    to the current number of created buffers, and it will check the validity of
115		    <structfield>memory</structfield> and <structfield>format.type</structfield>.
116		    If those are invalid -1 is returned and errno is set to &EINVAL;,
117		    otherwise <constant>VIDIOC_CREATE_BUFS</constant> returns 0. It will
118		    never set errno to &EBUSY; in this particular case.</entry>
119		  </row>
120		  <row>
121		    <entry>__u32</entry>
122		    <entry><structfield>memory</structfield></entry>
123		    <entry>Applications set this field to
124	<constant>V4L2_MEMORY_MMAP</constant>,
125	<constant>V4L2_MEMORY_DMABUF</constant> or
126	<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
127	/></entry>
128		  </row>
129		  <row>
130		    <entry>&v4l2-format;</entry>
131		    <entry><structfield>format</structfield></entry>
132		    <entry>Filled in by the application, preserved by the driver.</entry>
133		  </row>
134		  <row>
135		    <entry>__u32</entry>
136		    <entry><structfield>reserved</structfield>[8]</entry>
137		    <entry>A place holder for future extensions.</entry>
138		  </row>
139		</tbody>
140	      </tgroup>
141	    </table>
142	  </refsect1>
143	
144	  <refsect1>
145	    &return-value;
146	
147	    <variablelist>
148	      <varlistentry>
149		<term><errorcode>ENOMEM</errorcode></term>
150		<listitem>
151		  <para>No memory to allocate buffers for <link linkend="mmap">memory
152	mapped</link> I/O.</para>
153		</listitem>
154	      </varlistentry>
155	      <varlistentry>
156		<term><errorcode>EINVAL</errorcode></term>
157		<listitem>
158		  <para>The buffer type (<structfield>format.type</structfield> field),
159	requested I/O method (<structfield>memory</structfield>) or format
160	(<structfield>format</structfield> field) is not valid.</para>
161		</listitem>
162	      </varlistentry>
163	    </variablelist>
164	  </refsect1>
165	</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.