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 .. cpp:function:: int ioctl( int fd, int request, const int *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_STREAMON, VIDIOC_STREAMOFF
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
  37 the capture or output process during streaming
  38 (:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
  39 :ref:`DMABUF <dmabuf>`) I/O.
  40
  41 Capture hardware is disabled and no input buffers are filled (if there
  42 are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
  43 has been called. Output hardware is disabled and no video signal is
  44 produced until ``VIDIOC_STREAMON`` has been called. The ioctl will
  45 succeed when at least one output buffer is in the incoming queue.
  46
  47 Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
  48 been called for both the capture and output stream types.
  49
  50 If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
  51 queued.
  52
  53 The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
  54 in progress, unlocks any user pointer buffers locked in physical memory,
  55 and it removes all buffers from the incoming and outgoing queues. That
  56 means all images captured but not dequeued yet will be lost, likewise
  57 all images enqueued for output but not transmitted yet. I/O returns to
  58 the same state as after calling
  59 :ref:`VIDIOC_REQBUFS` and can be restarted
  60 accordingly.
  61
  62 If buffers have been queued with :ref:`VIDIOC_QBUF` and
  63 ``VIDIOC_STREAMOFF`` is called without ever having called
  64 ``VIDIOC_STREAMON``, then those queued buffers will also be removed from
  65 the incoming queue and all are returned to the same state as after
  66 calling :ref:`VIDIOC_REQBUFS` and can be restarted
  67 accordingly.
  68
  69 Both ioctls take a pointer to an integer, the desired buffer or stream
  70 type. This is the same as struct
  71 :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
  72
  73 If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
  74 or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
  75 then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
  76 but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
  77 state as mentioned above.
  78
  79 .. note:: Applications can be preempted for unknown periods right before
  80    or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
  81    no notion of starting or stopping "now". Buffer timestamps can be used
  82    to synchronize with other events.
  83
  84
  85 Return Value
  86 ============
  87
  88 On success 0 is returned, on error -1 and the ``errno`` variable is set
  89 appropriately. The generic error codes are described at the
  90 :ref:`Generic Error Codes <gen-errors>` chapter.
  91
  92 EINVAL
  93     The buffer ``type`` is not supported, or no buffers have been
  94     allocated (memory mapping) or enqueued (output) yet.
  95
  96 EPIPE
  97     The driver implements
  98     :ref:`pad-level format configuration <pad-level-formats>` and the
  99     pipeline configuration is invalid.
 100
 101 ENOLINK
 102     The driver implements Media Controller interface and the pipeline
 103     link configuration is invalid.