Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml

   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
  59 to the driver before actually enqueuing it, using the
  60 <constant>VIDIOC_QBUF</constant> ioctl, and to prepare it for future I/O.
  61 Such preparations may include cache invalidation or cleaning. Performing them
  62 in advance saves time during the actual I/O. In case such cache operations are
  63 not 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
  66 step.</para>
  67
  68     <para>The <structname>v4l2_buffer</structname> structure is
  69 specified 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
  86 supported, or the <structfield>index</structfield> is out of bounds,
  87 or 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>