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