[deliverable/linux.git] / Documentation / linux_tv / media / v4l / vidioc-streamon.rst

.. -*- coding: utf-8; mode: rst -*-

.. _VIDIOC_STREAMON:

***************************************
ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
***************************************

NAME
====

VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O

SYNOPSIS
========

.. cpp:function:: int ioctl( int fd, int request, const int *argp )


ARGUMENTS
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_STREAMON, VIDIOC_STREAMOFF

``argp``


DESCRIPTION
===========

The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
the capture or output process during streaming
(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
:ref:`DMABUF <dmabuf>`) I/O.

Capture hardware is disabled and no input buffers are filled (if there
are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
has been called. Output hardware is disabled and no video signal is
produced until ``VIDIOC_STREAMON`` has been called. The ioctl will
succeed when at least one output buffer is in the incoming queue.

Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
been called for both the capture and output stream types.

If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
queued.

The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
in progress, unlocks any user pointer buffers locked in physical memory,
and it removes all buffers from the incoming and outgoing queues. That
means all images captured but not dequeued yet will be lost, likewise
all images enqueued for output but not transmitted yet. I/O returns to
the same state as after calling
:ref:`VIDIOC_REQBUFS` and can be restarted
accordingly.

If buffers have been queued with :ref:`VIDIOC_QBUF` and
``VIDIOC_STREAMOFF`` is called without ever having called
``VIDIOC_STREAMON``, then those queued buffers will also be removed from
the incoming queue and all are returned to the same state as after
calling :ref:`VIDIOC_REQBUFS` and can be restarted
accordingly.

Both ioctls take a pointer to an integer, the desired buffer or stream
type. This is the same as struct
:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.

If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
state as mentioned above.

Note that applications can be preempted for unknown periods right before
or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
no notion of starting or stopping "now". Buffer timestamps can be used
to synchronize with other events.


RETURN VALUE
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The buffer ``type`` is not supported, or no buffers have been
    allocated (memory mapping) or enqueued (output) yet.

EPIPE
    The driver implements
    :ref:`pad-level format configuration <pad-level-formats>` and the
    pipeline configuration is invalid.

ENOLINK
    The driver implements Media Controller interface and the pipeline
    link configuration is invalid.
Commit	Line	Data
	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	SYNOPSIS
	15	========
	16
	17	.. cpp:function:: int ioctl( int fd, int request, const int *argp )
	18
	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.