vidioc-streamon.rst

  1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
  2.. c:namespace:: V4L
  3
  4.. _VIDIOC_STREAMON:
  5
  6***************************************
  7ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
  8***************************************
  9
 10Name
 11====
 12
 13VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
 14
 15Synopsis
 16========
 17
 18.. c:macro:: VIDIOC_STREAMON
 19
 20``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)``
 21
 22.. c:macro:: VIDIOC_STREAMOFF
 23
 24``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)``
 25
 26Arguments
 27=========
 28
 29``fd``
 30    File descriptor returned by :c:func:`open()`.
 31
 32``argp``
 33    Pointer to an integer.
 34
 35Description
 36===========
 37
 38The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
 39the capture or output process during streaming
 40(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
 41:ref:`DMABUF <dmabuf>`) I/O.
 42
 43Capture hardware is disabled and no input buffers are filled (if there
 44are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
 45has been called. Output hardware is disabled and no video signal is
 46produced until ``VIDIOC_STREAMON`` has been called.
 47
 48Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
 49been called for both the capture and output stream types.
 50
 51If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
 52queued.
 53
 54The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
 55in progress, unlocks any user pointer buffers locked in physical memory,
 56and it removes all buffers from the incoming and outgoing queues. That
 57means all images captured but not dequeued yet will be lost, likewise
 58all images enqueued for output but not transmitted yet. I/O returns to
 59the same state as after calling
 60:ref:`VIDIOC_REQBUFS` and can be restarted
 61accordingly.
 62
 63If 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
 66the incoming queue and all are returned to the same state as after
 67calling :ref:`VIDIOC_REQBUFS` and can be restarted
 68accordingly.
 69
 70Both ioctls take a pointer to an integer, the desired buffer or stream
 71type. This is the same as struct
 72: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 starting
 78state as mentioned above.
 79
 80.. note::
 81
 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.
 86
 87Return Value
 88============
 89
 90On success 0 is returned, on error -1 and the ``errno`` variable is set
 91appropriately. The generic error codes are described at the
 92:ref:`Generic Error Codes <gen-errors>` chapter.
 93
 94EINVAL
 95    The buffer ``type`` is not supported, or no buffers have been
 96    allocated (memory mapping) or enqueued (output) yet.
 97
 98EPIPE
 99    The driver implements
100    :ref:`pad-level format configuration <pad-level-formats>` and the
101    pipeline configuration is invalid.
102
103ENOLINK
104    The driver implements Media Controller interface and the pipeline
105    link configuration is invalid.