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     <para>Applications can optionally call the
  52 <constant>VIDIOC_PREPARE_BUF</constant> ioctl to pass ownership of the buffer
  53 to the driver before actually enqueuing it, using the
  54 <constant>VIDIOC_QBUF</constant> ioctl, and to prepare it for future I/O.
  55 Such preparations may include cache invalidation or cleaning. Performing them
  56 in advance saves time during the actual I/O. In case such cache operations are
  57 not required, the application can use one of
  58 <constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant> and
  59 <constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant> flags to skip the respective
  60 step.</para>
  61
  62     <para>The <structname>v4l2_buffer</structname> structure is
  63 specified in <xref linkend="buffer" />.</para>
  64   </refsect1>
  65
  66   <refsect1>
  67     &return-value;
  68
  69     <variablelist>
  70       <varlistentry>
  71         <term><errorcode>EBUSY</errorcode></term>
  72         <listitem>
  73           <para>File I/O is in progress.</para>
  74         </listitem>
  75       </varlistentry>
  76       <varlistentry>
  77         <term><errorcode>EINVAL</errorcode></term>
  78         <listitem>
  79           <para>The buffer <structfield>type</structfield> is not
  80 supported, or the <structfield>index</structfield> is out of bounds,
  81 or no buffers have been allocated yet, or the
  82 <structfield>userptr</structfield> or
  83 <structfield>length</structfield> are invalid.</para>
  84         </listitem>
  85       </varlistentry>
  86     </variablelist>
  87   </refsect1>
  88 </refentry>