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
54or output process during streaming (<link linkend="mmap">memory
55mapping</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
59buffers are filled (if there are any empty buffers in the incoming
60queue) until <constant>VIDIOC_STREAMON</constant> has been called.
61Output hardware is disabled and no video signal is
62produced until <constant>VIDIOC_STREAMON</constant> has been called.
63The ioctl will succeed when at least one output buffer is in the
64incoming 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
68and output stream types.</para>
69
70    <para>If <constant>VIDIOC_STREAMON</constant> fails then any already
71queued buffers will remain queued.</para>
72
73    <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of
74aborting or finishing any DMA in progress, unlocks any user pointer
75buffers locked in physical memory, and it removes all buffers from the
76incoming and outgoing queues. That means all images captured but not
77dequeued yet will be lost, likewise all images enqueued for output but
78not 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
83called <constant>VIDIOC_STREAMON</constant>, then those queued buffers
84will also be removed from the incoming queue and all are returned to the
85same state as after calling &VIDIOC-REQBUFS; and can be restarted
86accordingly.</para>
87
88    <para>Both ioctls take a pointer to an integer, the desired buffer or
89stream 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
93is already in progress, or if <constant>VIDIOC_STREAMOFF</constant> is called
94when streaming is already stopped, then 0 is returned. Nothing happens in the
95case of <constant>VIDIOC_STREAMON</constant>, but <constant>VIDIOC_STREAMOFF</constant>
96will return queued buffers to their starting state as mentioned above.</para>
97
98    <para>Note that applications can be preempted for unknown periods right
99before or after the <constant>VIDIOC_STREAMON</constant> or
100<constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of
101starting or stopping "now". Buffer timestamps can be used to
102synchronize 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    </variablelist>
127  </refsect1>
128</refentry>
129