media: docs-rst: Document memory-to-memory video decoder interface

One of the most common memory-to-memory device is the codec. Codecs

are more complicated than most and require additional setup for

their codec parameters. This is done through codec controls.

See :ref:`mpeg-controls`.

See :ref:`mpeg-controls`. More details on how to use codec memory-to-memory

devices are given in the following sections.

.. toctree::

    :maxdepth: 1

    dev-decoder

	to a multiple of the scale factor of any smaller planes. For

	example when the image format is YUV 4:2:0, ``width`` and

	``height`` must be multiples of two.

	For compressed formats that contain the resolution information encoded

	inside the stream, when fed to a stateful mem2mem decoder, the fields

	may be zero to rely on the decoder to detect the right values. For more

	details see :ref:`decoder` and format descriptions.

    * - __u32

      - ``pixelformat``

      - The pixel format or type of compression, set by the application.

  - Original author of the V4L2 API and documentation.

- Figa, Tomasz <tfiga@chromium.org>

  - Documented the memory-to-memory decoder interface.

- H Schimek, Michael <mschimek@gmx.at>

  - Original author of the V4L2 API and documentation.

  - Documented the Digital Video timings API.

- Osciak, Pawel <posciak@chromium.org>

  - Documented the memory-to-memory decoder interface.

- Osciak, Pawel <pawel@osciak.com>

  - Designed and documented the multi-planar API.

  - Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API.

**Copyright** |copy| 1999-2016: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari.

**Copyright** |copy| 1999-2018: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari, Tomasz Figa

Except when explicitly stated as GPL, programming examples within this

part can be used and distributed without restrictions.

A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON`

call sends an implicit START command to the decoder if it has not been

started yet.

started yet. Applies to both queues of mem2mem decoders.

A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`

call of a streaming file descriptor sends an implicit immediate STOP

command to the decoder, and all buffered data is discarded.

command to the decoder, and all buffered data is discarded. Applies to both

queues of mem2mem decoders.

These ioctls are optional, not all drivers may support them. They were

introduced in Linux 3.3.

In principle, these ioctls are optional, not all drivers may support them. They were

introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders

(as further documented in :ref:`decoder`).

.. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}|

	``V4L2_DEC_CMD_RESUME`` for that. This command has one flag:

	``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be

	muted when playing back at a non-standard speed.

	For a device implementing the :ref:`decoder`, once the drain sequence

	is initiated with the ``V4L2_DEC_CMD_STOP`` command, it must be driven

	to completion before this command can be invoked.  Any attempt to

	invoke the command while the drain sequence is in progress will trigger

	an ``EBUSY`` error code.  The command may be also used to restart the

	decoder in case of an implicit stop initiated by the decoder itself,

	without the ``V4L2_DEC_CMD_STOP`` being called explicitly. See

	:ref:`decoder` for more details.

    * - ``V4L2_DEC_CMD_STOP``

      - 1

      - Stop the decoder. When the decoder is already stopped, this

	command does nothing. This command has two flags: if

	``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set

	the picture to black after it stopped decoding. Otherwise the last

	image will repeat. mem2mem decoders will stop producing new frames

	altogether. They will send a ``V4L2_EVENT_EOS`` event when the

	last frame has been decoded and all frames are ready to be

	dequeued and will set the ``V4L2_BUF_FLAG_LAST`` buffer flag on

	the last buffer of the capture queue to indicate there will be no

	new buffers produced to dequeue. This buffer may be empty,

	indicated by the driver setting the ``bytesused`` field to 0. Once

	the ``V4L2_BUF_FLAG_LAST`` flag was set, the

	:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,

	but return an ``EPIPE`` error code. If

	image will repeat. If

	``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops

	immediately (ignoring the ``pts`` value), otherwise it will keep

	decoding until timestamp >= pts or until the last of the pending

	data from its internal buffers was decoded.

	For a device implementing the :ref:`decoder`, the command will initiate

	the drain sequence as documented in :ref:`decoder`.  No flags or other

	arguments are accepted in this case. Any attempt to invoke the command

	again before the sequence completes will trigger an ``EBUSY`` error

	code.

    * - ``V4L2_DEC_CMD_PAUSE``

      - 2

      - Pause the decoder. When the decoder has not been started yet, the

appropriately. The generic error codes are described at the

:ref:`Generic Error Codes <gen-errors>` chapter.

EBUSY

    A drain sequence of a device implementing the :ref:`decoder` is still in

    progress. It is not allowed to issue another decoder command until it

    completes.

EINVAL

    The ``cmd`` field is invalid.