Documentation/DocBook/media/v4l/vidioc-streamon.xml

   1 <refentry id="vidioc-streamon">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_STREAMON</refname>
   9     <refname>VIDIOC_STREAMOFF</refname>
  10     <refpurpose>Start or stop streaming 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>const int *<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_STREAMON, VIDIOC_STREAMOFF</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     <para>The <constant>VIDIOC_STREAMON</constant> and
  53 <constant>VIDIOC_STREAMOFF</constant> ioctl start and stop the capture
  54 or output process during streaming (<link linkend="mmap">memory
  55 mapping</link> or <link linkend="userp">user pointer</link>) I/O.</para>
  56
  57     <para>Specifically the capture hardware is disabled and no input
  58 buffers are filled (if there are any empty buffers in the incoming
  59 queue) until <constant>VIDIOC_STREAMON</constant> has been called.
  60 Accordingly the output hardware is disabled, no video signal is
  61 produced until <constant>VIDIOC_STREAMON</constant> has been called.
  62 The ioctl will succeed when at least one output buffer is in the
  63 incoming queue.</para>
  64
  65     <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of
  66 aborting or finishing any DMA in progress, unlocks any user pointer
  67 buffers locked in physical memory, and it removes all buffers from the
  68 incoming and outgoing queues. That means all images captured but not
  69 dequeued yet will be lost, likewise all images enqueued for output but
  70 not transmitted yet. I/O returns to the same state as after calling
  71 &VIDIOC-REQBUFS; and can be restarted accordingly.</para>
  72
  73     <para>Both ioctls take a pointer to an integer, the desired buffer or
  74 stream type. This is the same as &v4l2-requestbuffers;
  75 <structfield>type</structfield>.</para>
  76
  77     <para>If <constant>VIDIOC_STREAMON</constant> is called when streaming
  78 is already in progress, or if <constant>VIDIOC_STREAMOFF</constant> is called
  79 when streaming is already stopped, then the ioctl does nothing and 0 is
  80 returned.</para>
  81
  82     <para>Note that applications can be preempted for unknown periods right
  83 before or after the <constant>VIDIOC_STREAMON</constant> or
  84 <constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of
  85 starting or stopping "now". Buffer timestamps can be used to
  86 synchronize with other events.</para>
  87   </refsect1>
  88
  89   <refsect1>
  90     &return-value;
  91
  92     <variablelist>
  93       <varlistentry>
  94         <term><errorcode>EINVAL</errorcode></term>
  95         <listitem>
  96           <para>The buffer<structfield>type</structfield> is not supported,
  97           or no buffers have been allocated (memory mapping) or enqueued
  98           (output) yet.</para>
  99         </listitem>
 100       </varlistentry>
 101       <varlistentry>
 102         <term><errorcode>EPIPE</errorcode></term>
 103         <listitem>
 104           <para>The driver implements <link
 105           linkend="pad-level-formats">pad-level format configuration</link> and
 106           the pipeline configuration is invalid.
 107           </para>
 108         </listitem>
 109       </varlistentry>
 110     </variablelist>
 111   </refsect1>
 112 </refentry>