1<refentry id="vidioc-prepare-buf">
2  <refmeta>
3    <refentrytitle>ioctl VIDIOC_PREPARE_BUF</refentrytitle>
4    &manvol;
5  </refmeta>
6
7  <refnamediv>
8    <refname>VIDIOC_PREPARE_BUF</refname>
9    <refpurpose>Prepare a buffer for 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_buffer *<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_PREPARE_BUF</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    <note>
52      <title>Experimental</title>
53      <para>This is an <link linkend="experimental"> experimental </link>
54      interface and may change in the future.</para>
55    </note>
56
57    <para>Applications can optionally call the
58<constant>VIDIOC_PREPARE_BUF</constant> ioctl to pass ownership of the buffer
59to the driver before actually enqueuing it, using the
60<constant>VIDIOC_QBUF</constant> ioctl, and to prepare it for future I/O.
61Such preparations may include cache invalidation or cleaning. Performing them
62in advance saves time during the actual I/O. In case such cache operations are
63not required, the application can use one of
64<constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant> and
65<constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant> flags to skip the respective
66step.</para>
67
68    <para>The <structname>v4l2_buffer</structname> structure is
69specified in <xref linkend="buffer" />.</para>
70  </refsect1>
71
72  <refsect1>
73    &return-value;
74
75    <variablelist>
76      <varlistentry>
77	<term><errorcode>EBUSY</errorcode></term>
78	<listitem>
79	  <para>File I/O is in progress.</para>
80	</listitem>
81      </varlistentry>
82      <varlistentry>
83	<term><errorcode>EINVAL</errorcode></term>
84	<listitem>
85	  <para>The buffer <structfield>type</structfield> is not
86supported, or the <structfield>index</structfield> is out of bounds,
87or no buffers have been allocated yet, or the
88<structfield>userptr</structfield> or
89<structfield>length</structfield> are invalid.</para>
90	</listitem>
91      </varlistentry>
92    </variablelist>
93  </refsect1>
94</refentry>
95