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.9. Page generated on 2013-05-02 23:04 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 device buffers applications initialize relevant fields of
66	the <structname>v4l2_create_buffers</structname> structure. They set the
67	<structfield>type</structfield> field in the
68	&v4l2-format; structure, embedded in this
69	structure, to the respective stream or buffer type.
70	<structfield>count</structfield> must be set to the number of required buffers.
71	<structfield>memory</structfield> specifies the required I/O method. The
72	<structfield>format</structfield> field shall typically be filled in using
73	either the <constant>VIDIOC_TRY_FMT</constant> or
74	<constant>VIDIOC_G_FMT</constant> ioctl(). Additionally, applications can adjust
75	<structfield>sizeimage</structfield> fields to fit their specific needs. The
76	<structfield>reserved</structfield> array must be zeroed.</para>
77	
78	    <para>When the ioctl is called with a pointer to this structure the driver
79	will attempt to allocate up to the requested number of buffers and store the
80	actual number allocated and the starting index in the
81	<structfield>count</structfield> and the <structfield>index</structfield> fields
82	respectively. On return <structfield>count</structfield> can be smaller than
83	the number requested. The driver may also increase buffer sizes if required,
84	however, it will not update <structfield>sizeimage</structfield> field values.
85	The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that
86	information.</para>
87	
88	    <table pgwide="1" frame="none" id="v4l2-create-buffers">
89	      <title>struct <structname>v4l2_create_buffers</structname></title>
90	      <tgroup cols="3">
91		&cs-str;
92		<tbody valign="top">
93		  <row>
94		    <entry>__u32</entry>
95		    <entry><structfield>index</structfield></entry>
96		    <entry>The starting buffer index, returned by the driver.</entry>
97		  </row>
98		  <row>
99		    <entry>__u32</entry>
100		    <entry><structfield>count</structfield></entry>
101		    <entry>The number of buffers requested or granted. If count == 0, then
102		    <constant>VIDIOC_CREATE_BUFS</constant> will set <structfield>index</structfield>
103		    to the current number of created buffers, and it will check the validity of
104		    <structfield>memory</structfield> and <structfield>format.type</structfield>.
105		    If those are invalid -1 is returned and errno is set to &EINVAL;,
106		    otherwise <constant>VIDIOC_CREATE_BUFS</constant> returns 0. It will
107		    never set errno to &EBUSY; in this particular case.</entry>
108		  </row>
109		  <row>
110		    <entry>__u32</entry>
111		    <entry><structfield>memory</structfield></entry>
112		    <entry>Applications set this field to
113	<constant>V4L2_MEMORY_MMAP</constant>,
114	<constant>V4L2_MEMORY_DMABUF</constant> or
115	<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
116	/></entry>
117		  </row>
118		  <row>
119		    <entry>&v4l2-format;</entry>
120		    <entry><structfield>format</structfield></entry>
121		    <entry>Filled in by the application, preserved by the driver.</entry>
122		  </row>
123		  <row>
124		    <entry>__u32</entry>
125		    <entry><structfield>reserved</structfield>[8]</entry>
126		    <entry>A place holder for future extensions.</entry>
127		  </row>
128		</tbody>
129	      </tgroup>
130	    </table>
131	  </refsect1>
132	
133	  <refsect1>
134	    &return-value;
135	
136	    <variablelist>
137	      <varlistentry>
138		<term><errorcode>ENOMEM</errorcode></term>
139		<listitem>
140		  <para>No memory to allocate buffers for <link linkend="mmap">memory
141	mapped</link> I/O.</para>
142		</listitem>
143	      </varlistentry>
144	      <varlistentry>
145		<term><errorcode>EINVAL</errorcode></term>
146		<listitem>
147		  <para>The buffer type (<structfield>type</structfield> field) or the
148	requested I/O method (<structfield>memory</structfield>) is not
149	supported.</para>
150		</listitem>
151	      </varlistentry>
152	    </variablelist>
153	  </refsect1>
154	</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.