0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_STREAMON:
0005
0006 ***************************************
0007 ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
0008 ***************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_STREAMON
0019
0020 ``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)``
0021
0022 .. c:macro:: VIDIOC_STREAMOFF
0023
0024 ``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to an integer.
0034
0035 Description
0036 ===========
0037
0038 The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
0039 the capture or output process during streaming
0040 (:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
0041 :ref:`DMABUF <dmabuf>`) I/O.
0042
0043 Capture hardware is disabled and no input buffers are filled (if there
0044 are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
0045 has been called. Output hardware is disabled and no video signal is
0046 produced until ``VIDIOC_STREAMON`` has been called.
0047
0048 Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
0049 been called for both the capture and output stream types.
0050
0051 If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
0052 queued.
0053
0054 The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
0055 in progress, unlocks any user pointer buffers locked in physical memory,
0056 and it removes all buffers from the incoming and outgoing queues. That
0057 means all images captured but not dequeued yet will be lost, likewise
0058 all images enqueued for output but not transmitted yet. I/O returns to
0059 the same state as after calling
0060 :ref:`VIDIOC_REQBUFS` and can be restarted
0061 accordingly.
0062
0063 If buffers have been queued with :ref:`VIDIOC_QBUF` and
0064 ``VIDIOC_STREAMOFF`` is called without ever having called
0065 ``VIDIOC_STREAMON``, then those queued buffers will also be removed from
0066 the incoming queue and all are returned to the same state as after
0067 calling :ref:`VIDIOC_REQBUFS` and can be restarted
0068 accordingly.
0069
0070 Both ioctls take a pointer to an integer, the desired buffer or stream
0071 type. This is the same as struct
0072 :c:type:`v4l2_requestbuffers` ``type``.
0073
0074 If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
0075 or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
0076 then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
0077 but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
0078 state as mentioned above.
0079
0080 .. note::
0081
0082 Applications can be preempted for unknown periods right before
0083 or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
0084 no notion of starting or stopping "now". Buffer timestamps can be used
0085 to synchronize with other events.
0086
0087 Return Value
0088 ============
0089
0090 On success 0 is returned, on error -1 and the ``errno`` variable is set
0091 appropriately. The generic error codes are described at the
0092 :ref:`Generic Error Codes <gen-errors>` chapter.
0093
0094 EINVAL
0095 The buffer ``type`` is not supported, or no buffers have been
0096 allocated (memory mapping) or enqueued (output) yet.
0097
0098 EPIPE
0099 The driver implements
0100 :ref:`pad-level format configuration <pad-level-formats>` and the
0101 pipeline configuration is invalid.
0102
0103 ENOLINK
0104 The driver implements Media Controller interface and the pipeline
0105 link configuration is invalid.
