Documentation/media/uapi/v4l/vidioc-streamon.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_STREAMON:
  11
  12 ***************************************
  13 ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
  14 ***************************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_STREAMON, const int *argp )
  26     :name: VIDIOC_STREAMON
  27
  28 .. c:function:: int ioctl( int fd, VIDIOC_STREAMOFF, const int *argp )
  29     :name: VIDIOC_STREAMOFF
  30
  31
  32 Arguments
  33 =========
  34
  35 ``fd``
  36     File descriptor returned by :ref:`open() <func-open>`.
  37
  38 ``argp``
  39     Pointer to an integer.
  40
  41 Description
  42 ===========
  43
  44 The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
  45 the capture or output process during streaming
  46 (:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
  47 :ref:`DMABUF <dmabuf>`) I/O.
  48
  49 Capture hardware is disabled and no input buffers are filled (if there
  50 are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
  51 has been called. Output hardware is disabled and no video signal is
  52 produced until ``VIDIOC_STREAMON`` has been called. The ioctl will
  53 succeed when at least one output buffer is in the incoming queue.
  54
  55 Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
  56 been called for both the capture and output stream types.
  57
  58 If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
  59 queued.
  60
  61 The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
  62 in progress, unlocks any user pointer buffers locked in physical memory,
  63 and it removes all buffers from the incoming and outgoing queues. That
  64 means all images captured but not dequeued yet will be lost, likewise
  65 all images enqueued for output but not transmitted yet. I/O returns to
  66 the same state as after calling
  67 :ref:`VIDIOC_REQBUFS` and can be restarted
  68 accordingly.
  69
  70 If buffers have been queued with :ref:`VIDIOC_QBUF` and
  71 ``VIDIOC_STREAMOFF`` is called without ever having called
  72 ``VIDIOC_STREAMON``, then those queued buffers will also be removed from
  73 the incoming queue and all are returned to the same state as after
  74 calling :ref:`VIDIOC_REQBUFS` and can be restarted
  75 accordingly.
  76
  77 Both ioctls take a pointer to an integer, the desired buffer or stream
  78 type. This is the same as struct
  79 :c:type:`v4l2_requestbuffers` ``type``.
  80
  81 If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
  82 or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
  83 then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
  84 but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
  85 state as mentioned above.
  86
  87 .. note::
  88
  89    Applications can be preempted for unknown periods right before
  90    or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
  91    no notion of starting or stopping "now". Buffer timestamps can be used
  92    to synchronize with other events.
  93
  94
  95 Return Value
  96 ============
  97
  98 On success 0 is returned, on error -1 and the ``errno`` variable is set
  99 appropriately. The generic error codes are described at the
 100 :ref:`Generic Error Codes <gen-errors>` chapter.
 101
 102 EINVAL
 103     The buffer ``type`` is not supported, or no buffers have been
 104     allocated (memory mapping) or enqueued (output) yet.
 105
 106 EPIPE
 107     The driver implements
 108     :ref:`pad-level format configuration <pad-level-formats>` and the
 109     pipeline configuration is invalid.
 110
 111 ENOLINK
 112     The driver implements Media Controller interface and the pipeline
 113     link configuration is invalid.