1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
6 ***************************************
7 ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
8 ***************************************
13 VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
18 .. c:macro:: VIDIOC_STREAMON
20 ``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)``
22 .. c:macro:: VIDIOC_STREAMOFF
24 ``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)``
30 File descriptor returned by :c:func:`open()`.
33 Pointer to an integer.
38 The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
39 the capture or output process during streaming
40 (:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
41 :ref:`DMABUF <dmabuf>`) I/O.
43 Capture hardware is disabled and no input buffers are filled (if there
44 are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
45 has been called. Output hardware is disabled and no video signal is
46 produced until ``VIDIOC_STREAMON`` has been called.
48 Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
49 been called for both the capture and output stream types.
51 If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
54 The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
55 in progress, unlocks any user pointer buffers locked in physical memory,
56 and it removes all buffers from the incoming and outgoing queues. That
57 means all images captured but not dequeued yet will be lost, likewise
58 all images enqueued for output but not transmitted yet. I/O returns to
59 the same state as after calling
60 :ref:`VIDIOC_REQBUFS` and can be restarted
63 If buffers have been queued with :ref:`VIDIOC_QBUF` and
64 ``VIDIOC_STREAMOFF`` is called without ever having called
65 ``VIDIOC_STREAMON``, then those queued buffers will also be removed from
66 the incoming queue and all are returned to the same state as after
67 calling :ref:`VIDIOC_REQBUFS` and can be restarted
70 Both ioctls take a pointer to an integer, the desired buffer or stream
71 type. This is the same as struct
72 :c:type:`v4l2_requestbuffers` ``type``.
74 If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
75 or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
76 then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
77 but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
78 state as mentioned above.
82 Applications can be preempted for unknown periods right before
83 or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
84 no notion of starting or stopping "now". Buffer timestamps can be used
85 to synchronize with other events.
90 On success 0 is returned, on error -1 and the ``errno`` variable is set
91 appropriately. The generic error codes are described at the
92 :ref:`Generic Error Codes <gen-errors>` chapter.
95 The buffer ``type`` is not supported, or no buffers have been
96 allocated (memory mapping) or enqueued (output) yet.
100 :ref:`pad-level format configuration <pad-level-formats>` and the
101 pipeline configuration is invalid.
104 The driver implements Media Controller interface and the pipeline
105 link configuration is invalid.