106 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_STREAMON:5 6***************************************7ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF8***************************************9 10Name11====12 13VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O14 15Synopsis16========17 18.. c:macro:: VIDIOC_STREAMON19 20``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)``21 22.. c:macro:: VIDIOC_STREAMOFF23 24``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)``25 26Arguments27=========28 29``fd``30 File descriptor returned by :c:func:`open()`.31 32``argp``33 Pointer to an integer.34 35Description36===========37 38The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop39the capture or output process during streaming40(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or41:ref:`DMABUF <dmabuf>`) I/O.42 43Capture hardware is disabled and no input buffers are filled (if there44are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``45has been called. Output hardware is disabled and no video signal is46produced until ``VIDIOC_STREAMON`` has been called.47 48Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has49been called for both the capture and output stream types.50 51If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain52queued.53 54The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA55in progress, unlocks any user pointer buffers locked in physical memory,56and it removes all buffers from the incoming and outgoing queues. That57means all images captured but not dequeued yet will be lost, likewise58all images enqueued for output but not transmitted yet. I/O returns to59the same state as after calling60:ref:`VIDIOC_REQBUFS` and can be restarted61accordingly.62 63If buffers have been queued with :ref:`VIDIOC_QBUF` and64``VIDIOC_STREAMOFF`` is called without ever having called65``VIDIOC_STREAMON``, then those queued buffers will also be removed from66the incoming queue and all are returned to the same state as after67calling :ref:`VIDIOC_REQBUFS` and can be restarted68accordingly.69 70Both ioctls take a pointer to an integer, the desired buffer or stream71type. This is the same as struct72:c:type:`v4l2_requestbuffers` ``type``.73 74If ``VIDIOC_STREAMON`` is called when streaming is already in progress,75or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,76then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,77but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting78state as mentioned above.79 80.. note::81 82 Applications can be preempted for unknown periods right before83 or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is84 no notion of starting or stopping "now". Buffer timestamps can be used85 to synchronize with other events.86 87Return Value88============89 90On success 0 is returned, on error -1 and the ``errno`` variable is set91appropriately. The generic error codes are described at the92:ref:`Generic Error Codes <gen-errors>` chapter.93 94EINVAL95 The buffer ``type`` is not supported, or no buffers have been96 allocated (memory mapping) or enqueued (output) yet.97 98EPIPE99 The driver implements100 :ref:`pad-level format configuration <pad-level-formats>` and the101 pipeline configuration is invalid.102 103ENOLINK104 The driver implements Media Controller interface and the pipeline105 link configuration is invalid.106