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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_STREAMON:
   4
   5 ***************************************
   6 ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
   7 ***************************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, VIDIOC_STREAMON, const int *argp )
  19     :name: VIDIOC_STREAMON
  20
  21 .. c:function:: int ioctl( int fd, VIDIOC_STREAMOFF, const int *argp )
  22     :name: VIDIOC_STREAMOFF
  23
  24
  25 Arguments
  26 =========
  27
  28 ``fd``
  29     File descriptor returned by :ref:`open() <func-open>`.
  30
  31 ``argp``
  32     Pointer to an integer.
  33
  34 Description
  35 ===========
  36
  37 The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
  38 the capture or output process during streaming
  39 (:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
  40 :ref:`DMABUF <dmabuf>`) I/O.
  41
  42 Capture hardware is disabled and no input buffers are filled (if there
  43 are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
  44 has been called. Output hardware is disabled and no video signal is
  45 produced until ``VIDIOC_STREAMON`` has been called. The ioctl will
  46 succeed when at least one output buffer is in the incoming queue.
  47
  48 Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
  49 been called for both the capture and output stream types.
  50
  51 If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
  52 queued.
  53
  54 The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
  55 in progress, unlocks any user pointer buffers locked in physical memory,
  56 and it removes all buffers from the incoming and outgoing queues. That
  57 means all images captured but not dequeued yet will be lost, likewise
  58 all images enqueued for output but not transmitted yet. I/O returns to
  59 the same state as after calling
  60 :ref:`VIDIOC_REQBUFS` and can be restarted
  61 accordingly.
  62
  63 If 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
  66 the incoming queue and all are returned to the same state as after
  67 calling :ref:`VIDIOC_REQBUFS` and can be restarted
  68 accordingly.
  69
  70 Both ioctls take a pointer to an integer, the desired buffer or stream
  71 type. This is the same as struct
  72 :c:type:`v4l2_requestbuffers` ``type``.
  73
  74 If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
  75 or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
  76 then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
  77 but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
  78 state 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
  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.