1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _VIDIOC_STREAMON:
11
12***************************************
13ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
14***************************************
15
16Name
17====
18
19VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_STREAMON, const int *argp )
26    :name: VIDIOC_STREAMON
27
28.. c:function:: int ioctl( int fd, VIDIOC_STREAMOFF, const int *argp )
29    :name: VIDIOC_STREAMOFF
30
31
32Arguments
33=========
34
35``fd``
36    File descriptor returned by :ref:`open() <func-open>`.
37
38``argp``
39    Pointer to an integer.
40
41Description
42===========
43
44The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
45the capture or output process during streaming
46(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
47:ref:`DMABUF <dmabuf>`) I/O.
48
49Capture hardware is disabled and no input buffers are filled (if there
50are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
51has been called. Output hardware is disabled and no video signal is
52produced until ``VIDIOC_STREAMON`` has been called. The ioctl will
53succeed when at least one output buffer is in the incoming queue.
54
55Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
56been called for both the capture and output stream types.
57
58If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
59queued.
60
61The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
62in progress, unlocks any user pointer buffers locked in physical memory,
63and it removes all buffers from the incoming and outgoing queues. That
64means all images captured but not dequeued yet will be lost, likewise
65all images enqueued for output but not transmitted yet. I/O returns to
66the same state as after calling
67:ref:`VIDIOC_REQBUFS` and can be restarted
68accordingly.
69
70If buffers have been queued with :ref:`VIDIOC_QBUF` and
71``VIDIOC_STREAMOFF`` is called without ever having called
72``VIDIOC_STREAMON``, then those queued buffers will also be removed from
73the incoming queue and all are returned to the same state as after
74calling :ref:`VIDIOC_REQBUFS` and can be restarted
75accordingly.
76
77Both ioctls take a pointer to an integer, the desired buffer or stream
78type. This is the same as struct
79:c:type:`v4l2_requestbuffers` ``type``.
80
81If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
82or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
83then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
84but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
85state as mentioned above.
86
87.. note::
88
89   Applications can be preempted for unknown periods right before
90   or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
91   no notion of starting or stopping "now". Buffer timestamps can be used
92   to synchronize with other events.
93
94
95Return Value
96============
97
98On success 0 is returned, on error -1 and the ``errno`` variable is set
99appropriately. The generic error codes are described at the
100:ref:`Generic Error Codes <gen-errors>` chapter.
101
102EINVAL
103    The buffer ``type`` is not supported, or no buffers have been
104    allocated (memory mapping) or enqueued (output) yet.
105
106EPIPE
107    The driver implements
108    :ref:`pad-level format configuration <pad-level-formats>` and the
109    pipeline configuration is invalid.
110
111ENOLINK
112    The driver implements Media Controller interface and the pipeline
113    link configuration is invalid.
114