Documentation/userspace-api/media/v4l/vidioc-streamon.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_STREAMON:
   5
   6 ***************************************
   7 ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
   8 ***************************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
  14
  15 Synopsis
  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
  26 Arguments
  27 =========
  28
  29 ``fd``
  30     File descriptor returned by :c:func:`open()`.
  31
  32 ``argp``
  33     Pointer to an integer.
  34
  35 Description
  36 ===========
  37
  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.
  42
  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. The ioctl will
  47 succeed when at least one output buffer is in the incoming queue.
  48
  49 Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
  50 been called for both the capture and output stream types.
  51
  52 If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
  53 queued.
  54
  55 The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
  56 in progress, unlocks any user pointer buffers locked in physical memory,
  57 and it removes all buffers from the incoming and outgoing queues. That
  58 means all images captured but not dequeued yet will be lost, likewise
  59 all images enqueued for output but not transmitted yet. I/O returns to
  60 the same state as after calling
  61 :ref:`VIDIOC_REQBUFS` and can be restarted
  62 accordingly.
  63
  64 If buffers have been queued with :ref:`VIDIOC_QBUF` and
  65 ``VIDIOC_STREAMOFF`` is called without ever having called
  66 ``VIDIOC_STREAMON``, then those queued buffers will also be removed from
  67 the incoming queue and all are returned to the same state as after
  68 calling :ref:`VIDIOC_REQBUFS` and can be restarted
  69 accordingly.
  70
  71 Both ioctls take a pointer to an integer, the desired buffer or stream
  72 type. This is the same as struct
  73 :c:type:`v4l2_requestbuffers` ``type``.
  74
  75 If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
  76 or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
  77 then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
  78 but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
  79 state as mentioned above.
  80
  81 .. note::
  82
  83    Applications can be preempted for unknown periods right before
  84    or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
  85    no notion of starting or stopping "now". Buffer timestamps can be used
  86    to synchronize with other events.
  87
  88 Return Value
  89 ============
  90
  91 On success 0 is returned, on error -1 and the ``errno`` variable is set
  92 appropriately. The generic error codes are described at the
  93 :ref:`Generic Error Codes <gen-errors>` chapter.
  94
  95 EINVAL
  96     The buffer ``type`` is not supported, or no buffers have been
  97     allocated (memory mapping) or enqueued (output) yet.
  98
  99 EPIPE
 100     The driver implements
 101     :ref:`pad-level format configuration <pad-level-formats>` and the
 102     pipeline configuration is invalid.
 103
 104 ENOLINK
 105     The driver implements Media Controller interface and the pipeline
 106     link configuration is invalid.