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>, <link linkend="userp">user pointer</link> or
  56 <link linkend="dmabuf">DMABUF</link>) I/O.</para>
  57
  58     <para>Capture hardware is disabled and no input
  59 buffers are filled (if there are any empty buffers in the incoming
  60 queue) until <constant>VIDIOC_STREAMON</constant> has been called.
  61 Output hardware is disabled and no video signal is
  62 produced until <constant>VIDIOC_STREAMON</constant> has been called.
  63 The ioctl will succeed when at least one output buffer is in the
  64 incoming queue.</para>
  65
  66     <para>Memory-to-memory devices will not start until
  67 <constant>VIDIOC_STREAMON</constant> has been called for both the capture
  68 and output stream types.</para>
  69
  70     <para>If <constant>VIDIOC_STREAMON</constant> fails then any already
  71 queued buffers will remain queued.</para>
  72
  73     <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of
  74 aborting or finishing any DMA in progress, unlocks any user pointer
  75 buffers locked in physical memory, and it removes all buffers from the
  76 incoming and outgoing queues. That means all images captured but not
  77 dequeued yet will be lost, likewise all images enqueued for output but
  78 not transmitted yet. I/O returns to the same state as after calling
  79 &VIDIOC-REQBUFS; and can be restarted accordingly.</para>
  80
  81     <para>If buffers have been queued with &VIDIOC-QBUF; and
  82 <constant>VIDIOC_STREAMOFF</constant> is called without ever having
  83 called <constant>VIDIOC_STREAMON</constant>, then those queued buffers
  84 will also be removed from the incoming queue and all are returned to the
  85 same state as after calling &VIDIOC-REQBUFS; and can be restarted
  86 accordingly.</para>
  87
  88     <para>Both ioctls take a pointer to an integer, the desired buffer or
  89 stream type. This is the same as &v4l2-requestbuffers;
  90 <structfield>type</structfield>.</para>
  91
  92     <para>If <constant>VIDIOC_STREAMON</constant> is called when streaming
  93 is already in progress, or if <constant>VIDIOC_STREAMOFF</constant> is called
  94 when streaming is already stopped, then 0 is returned. Nothing happens in the
  95 case of <constant>VIDIOC_STREAMON</constant>, but <constant>VIDIOC_STREAMOFF</constant>
  96 will return queued buffers to their starting state as mentioned above.</para>
  97
  98     <para>Note that applications can be preempted for unknown periods right
  99 before or after the <constant>VIDIOC_STREAMON</constant> or
 100 <constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of
 101 starting or stopping "now". Buffer timestamps can be used to
 102 synchronize with other events.</para>
 103   </refsect1>
 104
 105   <refsect1>
 106     &return-value;
 107
 108     <variablelist>
 109       <varlistentry>
 110         <term><errorcode>EINVAL</errorcode></term>
 111         <listitem>
 112           <para>The buffer <structfield>type</structfield> is not supported,
 113           or no buffers have been allocated (memory mapping) or enqueued
 114           (output) yet.</para>
 115         </listitem>
 116       </varlistentry>
 117       <varlistentry>
 118         <term><errorcode>EPIPE</errorcode></term>
 119         <listitem>
 120           <para>The driver implements <link
 121           linkend="pad-level-formats">pad-level format configuration</link> and
 122           the pipeline configuration is invalid.
 123           </para>
 124         </listitem>
 125       </varlistentry>
 126       <varlistentry>
 127         <term><errorcode>ENOLINK</errorcode></term>
 128         <listitem>
 129           <para>The driver implements Media Controller interface and
 130           the pipeline link configuration is invalid.
 131           </para>
 132         </listitem>
 133       </varlistentry>
 134     </variablelist>
 135   </refsect1>
 136 </refentry>