aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/v4l/vidioc-reqbufs.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/v4l/vidioc-reqbufs.xml')
-rw-r--r--Documentation/DocBook/v4l/vidioc-reqbufs.xml160
1 files changed, 160 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/v4l/vidioc-reqbufs.xml
new file mode 100644
index 000000000000..bab38084454f
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-reqbufs.xml
@@ -0,0 +1,160 @@
1<refentry id="vidioc-reqbufs">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_REQBUFS</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_REQBUFS</refname>
9 <refpurpose>Initiate Memory Mapping or User Pointer I/O</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct v4l2_requestbuffers *<parameter>argp</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>fd</parameter></term>
29 <listitem>
30 <para>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_REQBUFS</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>This ioctl is used to initiate <link linkend="mmap">memory
52mapped</link> or <link linkend="userp">user pointer</link>
53I/O. Memory mapped buffers are located in device memory and must be
54allocated with this ioctl before they can be mapped into the
55application's address space. User buffers are allocated by
56applications themselves, and this ioctl is merely used to switch the
57driver into user pointer I/O mode.</para>
58
59 <para>To allocate device buffers applications initialize three
60fields of a <structname>v4l2_requestbuffers</structname> structure.
61They set the <structfield>type</structfield> field to the respective
62stream or buffer type, the <structfield>count</structfield> field to
63the desired number of buffers, and <structfield>memory</structfield>
64must be set to <constant>V4L2_MEMORY_MMAP</constant>. When the ioctl
65is called with a pointer to this structure the driver attempts to
66allocate the requested number of buffers and stores the actual number
67allocated in the <structfield>count</structfield> field. It can be
68smaller than the number requested, even zero, when the driver runs out
69of free memory. A larger number is possible when the driver requires
70more buffers to function correctly.<footnote>
71 <para>For example video output requires at least two buffers,
72one displayed and one filled by the application.</para>
73 </footnote> When memory mapping I/O is not supported the ioctl
74returns an &EINVAL;.</para>
75
76 <para>Applications can call <constant>VIDIOC_REQBUFS</constant>
77again to change the number of buffers, however this cannot succeed
78when any buffers are still mapped. A <structfield>count</structfield>
79value of zero frees all buffers, after aborting or finishing any DMA
80in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no
81reason why munmap()ping one or even all buffers must imply
82streamoff.--></para>
83
84 <para>To negotiate user pointer I/O, applications initialize only
85the <structfield>type</structfield> field and set
86<structfield>memory</structfield> to
87<constant>V4L2_MEMORY_USERPTR</constant>. When the ioctl is called
88with a pointer to this structure the driver prepares for user pointer
89I/O, when this I/O method is not supported the ioctl returns an
90&EINVAL;.</para>
91
92 <table pgwide="1" frame="none" id="v4l2-requestbuffers">
93 <title>struct <structname>v4l2_requestbuffers</structname></title>
94 <tgroup cols="3">
95 &cs-str;
96 <tbody valign="top">
97 <row>
98 <entry>__u32</entry>
99 <entry><structfield>count</structfield></entry>
100 <entry>The number of buffers requested or granted. This
101field is only used when <structfield>memory</structfield> is set to
102<constant>V4L2_MEMORY_MMAP</constant>.</entry>
103 </row>
104 <row>
105 <entry>&v4l2-buf-type;</entry>
106 <entry><structfield>type</structfield></entry>
107 <entry>Type of the stream or buffers, this is the same
108as the &v4l2-format; <structfield>type</structfield> field. See <xref
109 linkend="v4l2-buf-type" /> for valid values.</entry>
110 </row>
111 <row>
112 <entry>&v4l2-memory;</entry>
113 <entry><structfield>memory</structfield></entry>
114 <entry>Applications set this field to
115<constant>V4L2_MEMORY_MMAP</constant> or
116<constant>V4L2_MEMORY_USERPTR</constant>.</entry>
117 </row>
118 <row>
119 <entry>__u32</entry>
120 <entry><structfield>reserved</structfield>[2]</entry>
121 <entry>A place holder for future extensions and custom
122(driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and
123higher.</entry>
124 </row>
125 </tbody>
126 </tgroup>
127 </table>
128 </refsect1>
129
130 <refsect1>
131 &return-value;
132
133 <variablelist>
134 <varlistentry>
135 <term><errorcode>EBUSY</errorcode></term>
136 <listitem>
137 <para>The driver supports multiple opens and I/O is already
138in progress, or reallocation of buffers was attempted although one or
139more are still mapped.</para>
140 </listitem>
141 </varlistentry>
142 <varlistentry>
143 <term><errorcode>EINVAL</errorcode></term>
144 <listitem>
145 <para>The buffer type (<structfield>type</structfield> field) or the
146requested I/O method (<structfield>memory</structfield>) is not
147supported.</para>
148 </listitem>
149 </varlistentry>
150 </variablelist>
151 </refsect1>
152</refentry>
153
154<!--
155Local Variables:
156mode: sgml
157sgml-parent-document: "v4l2.sgml"
158indent-tabs-mode: nil
159End:
160-->