[PATCHv4 0/2] Document memory-to-memory video codec interfaces

[PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Hans Verkuil]

Since Thomasz was very busy with other things, I've taken over this
patch series. This v4 includes his draft changes and additional changes
from me.

This series attempts to add the documentation of what was discussed
during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
later Embedded Linux Conference Europe 2014 in Düsseldorf and then
eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
video team (but mostly in a cosmetic way or making the document more
precise), during the several years of Chrome OS using the APIs in
production.

Note that most, if not all, of the API is already implemented in
existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
this series is just to formalize what we already have.

Thanks everyone for the huge amount of useful comments to previous
versions of this series. Much of the credits should go to Pawel Osciak
too, for writing most of the original text of the initial RFC.

This v4 incorporates all known comments (let me know if I missed
something!) and should be complete for the decoder.

For the encoder there are two remaining TODOs for the API:

1) Setting the frame rate so bitrate control can make sense, since
   they need to know this information.

   Suggested solution: require support for ENUM_FRAMEINTERVALS for the
   coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
   (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
   S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
   this is not a CAPTURE vs OUTPUT thing, it is global to both queues.

2) Interactions between OUTPUT and CAPTURE formats.

   The main problem is what to do if the capture sizeimage is too small
   for the OUTPUT resolution when streaming starts.

   Proposal: width and height of S_FMT(OUTPUT) are used to
   calculate a minimum sizeimage (app may request more). This is
   driver-specific.

   V4L2_FMT_FLAG_FIXED_RESOLUTION is always set for codec formats
   for the encoder (i.e. we don't support mid-stream resolution
   changes for now) and V4L2_EVENT_SOURCE_CHANGE is not
   supported. See https://patchwork.linuxtv.org/patch/56478/ for
   the patch adding this flag.

   Of course, if we start to support mid-stream resolution
   changes (or other changes that require a source change event),
   then this flag should be dropped by the encoder driver and
   documentation on how to handle the source change event should
   be documented in the encoder spec. I prefer to postpone this
   until we have an encoder than can actually do mid-stream
   resolution changes.

   If sizeimage of the OUTPUT is too small for the CAPTURE
   resolution and V4L2_EVENT_SOURCE_CHANGE is not supported,
   then the second STREAMON (either CAPTURE or OUTPUT) will
   return -ENOMEM since there is not enough memory to do the
   encode.

   If V4L2_FMT_FLAG_FIXED_RESOLUTION is set (i.e. that should
   be the case for all current encoders), then any bitrate controls
   will be limited in range to what the current state (CAPTURE and
   OUTPUT formats and frame rate) supports.

Comments regarding these two encoder proposals are welcome!

Regards,

	Hans

Changes since v3:

- Lots of stylistic fixes and fixing typos/grammar/etc.

Decoder:

- width/height for S_FMT(OUTPUT):

  Expects that the output width and height is always a valid
  resolution (i.e. never 0x0), and G/S/TRY_FMT and REQBUFS will use that
  instead of returning an error. Note that this resolution is a placeholder
  until the actual resolution is parsed from the stream.

- Dropped step 3 (Query the minimum number of buffers required for the CAPTURE
  queue via VIDIOC_G_CTRL().) in the Capture Setup section. It seems to be
  a left-over from earlier versions. The same information is also in Step 10,
  so no need to have this in two places.

- Added step 5 in the Capture Setup section: set COMPOSE rectangle if needed.

- VIDIO_DECODER_CMD: document EBUSY return while draining the queue.

Encoder:

- width/height for S_FMT(CAPTURE): The width/height for the CAPTURE format
  are marked as read-only and are based on the encoders current state such
  as the OUTPUT format.

- Drop TGT_COMPOSE support in the encoder: there are currently
  no encoders that can do composing/scaling.

- Document corner cases in the Drain sequence

- Document error handling.

- VIDIO_ENCODER_CMD: document EBUSY return while draining the queue.

Changes since v2:
(https://lore.kernel.org/patchwork/cover/1002474/)
Decoder:
 - Specified that the initial source change event is signaled
   regardless of whether the client-set format matches the
   stream format.
 - Dropped V4L2_CID_MIN_BUFFERS_FOR_OUTPUT since it's meaningless
   for the bitstream input buffers of decoders.
 - Explicitly stated that VIDIOC_REQBUFS is not allowed on CAPTURE
   if the stream information is not available.
 - Described decode error handling.
 - Mentioned that timestamps can be observed after a seek to
   determine whether the CAPTURE buffers originated from before
   or after the seek.
 - Explicitly stated that after a pair of V4L2_DEC_CMD_STOP and
   V4L2_DEC_CMD_START, the decoder is not reset and preserves
   all the state.

Encoder:
 - Specified that width and height of CAPTURE format are ignored
   and always zero.
 - Explicitly noted the common use case for the CROP target with
   macroblock-unaligned video resolutions.
 - Added a reference to Request API.
 - Dropped V4L2_CID_MIN_BUFFERS_FOR_CAPTURE since it's meaningless
   for the bitstream output buffers of encoders.
 - Explicitly stated that after a pair of V4L2_ENC_CMD_STOP and
   V4L2_ENC_CMD_START, the encoder is not reset and preserves
   all the state.

General:
 - Dropped format enumeration from "Initialization", since it's already
   a part of "Querying capabilities".
 - Many spelling, grammar, stylistic, etc. changes.
 - Changed the style of note blocks.
 - Rebased onto Hans' documentation cleanup series.
   (https://patchwork.kernel.org/cover/10775407/
    https://patchwork.kernel.org/patch/10776737/)
 - Moved the interfaces under the "Video Memory-To-Memory Interface"
   section.

For changes since v1 see the v2:
https://lore.kernel.org/patchwork/cover/1002474/

For changes since RFC see the v1:
https://patchwork.kernel.org/cover/10542207/

Tomasz Figa (2):
  media: docs-rst: Document memory-to-memory video decoder interface
  media: docs-rst: Document memory-to-memory video encoder interface

 Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
 Documentation/media/uapi/v4l/dev-encoder.rst  |  608 +++++++++
 Documentation/media/uapi/v4l/dev-mem2mem.rst  |    9 +-
 Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |   10 +
 Documentation/media/uapi/v4l/v4l2.rst         |   12 +-
 .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
 .../media/uapi/v4l/vidioc-encoder-cmd.rst     |   51 +-
 7 files changed, 1779 insertions(+), 36 deletions(-)
 create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
 create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst

-- 
2.20.1

[PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Hans Verkuil]

From: Tomasz Figa <tfiga@chromium.org>

Due to complexity of the video decoding process, the V4L2 drivers of
stateful decoder hardware require specific sequences of V4L2 API calls
to be followed. These include capability enumeration, initialization,
decoding, seek, pause, dynamic resolution change, drain and end of
stream.

Specifics of the above have been discussed during Media Workshops at
LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
Conference Europe 2014 in Düsseldorf. The de facto Codec API that
originated at those events was later implemented by the drivers we already
have merged in mainline, such as s5p-mfc or coda.

The only thing missing was the real specification included as a part of
Linux Media documentation. Fix it now and document the decoder part of
the Codec API.

Signed-off-by: Tomasz Figa <tfiga@chromium.org>
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
---
 Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
 Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
 Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
 Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
 .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
 5 files changed, 1132 insertions(+), 16 deletions(-)
 create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst

diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst
new file mode 100644
index 000000000000..b106f2d97c48
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-decoder.rst
@@ -0,0 +1,1084 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _decoder:
+
+*************************************************
+Memory-to-memory Stateful Video Decoder Interface
+*************************************************
+
+A stateful video decoder takes complete chunks of the bitstream (e.g. Annex-B
+H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
+display order. The decoder is expected not to require any additional information
+from the client to process these buffers.
+
+Performing software parsing, processing etc. of the stream in the driver in
+order to support this interface is strongly discouraged. In case such
+operations are needed, use of the Stateless Video Decoder Interface (in
+development) is strongly advised.
+
+Conventions and notation used in this document
+==============================================
+
+1. The general V4L2 API rules apply if not specified in this document
+   otherwise.
+
+2. The meaning of words "must", "may", "should", etc. is as per `RFC
+   2119 <https://tools.ietf.org/html/rfc2119>`_.
+
+3. All steps not marked "optional" are required.
+
+4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
+   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
+   unless specified otherwise.
+
+5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
+   used interchangeably with multi-planar API, unless specified otherwise,
+   depending on decoder capabilities and following the general V4L2 guidelines.
+
+6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
+   [0..2]: i = 0, 1, 2.
+
+7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
+   queue containing data that resulted from processing buffer A.
+
+.. _decoder-glossary:
+
+Glossary
+========
+
+CAPTURE
+   the destination buffer queue; for decoders, the queue of buffers containing
+   decoded frames; for encoders, the queue of buffers containing an encoded
+   bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
+   ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
+   into ``CAPTURE`` buffers.
+
+client
+   the application communicating with the decoder or encoder implementing
+   this interface.
+
+coded format
+   encoded/compressed video bitstream format (e.g. H.264, VP8, etc.); see
+   also: raw format.
+
+coded height
+   height for given coded resolution.
+
+coded resolution
+   stream resolution in pixels aligned to codec and hardware requirements;
+   typically visible resolution rounded up to full macroblocks;
+   see also: visible resolution.
+
+coded width
+   width for given coded resolution.
+
+decode order
+   the order in which frames are decoded; may differ from display order if the
+   coded format includes a feature of frame reordering; for decoders,
+   ``OUTPUT`` buffers must be queued by the client in decode order; for
+   encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
+
+destination
+   data resulting from the decode process; see ``CAPTURE``.
+
+display order
+   the order in which frames must be displayed; for encoders, ``OUTPUT``
+   buffers must be queued by the client in display order; for decoders,
+   ``CAPTURE`` buffers must be returned by the decoder in display order.
+
+DPB
+   Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
+   raw frame available for reference in further decoding steps.
+
+EOS
+   end of stream.
+
+IDR
+   Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
+   stream, which clears the list of earlier reference frames (DPBs).
+
+keyframe
+   an encoded frame that does not reference frames decoded earlier, i.e.
+   can be decoded fully on its own.
+
+macroblock
+   a processing unit in image and video compression formats based on linear
+   block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
+   popular codecs the size is 16x16 samples (pixels).
+
+OUTPUT
+   the source buffer queue; for decoders, the queue of buffers containing
+   an encoded bitstream; for encoders, the queue of buffers containing raw
+   frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
+   ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
+   from ``OUTPUT`` buffers.
+
+PPS
+   Picture Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
+
+raw format
+   uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
+
+resume point
+   a point in the bitstream from which decoding may start/continue, without
+   any previous state/data present, e.g.: a keyframe (VP8/VP9) or
+   SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
+   of a new stream, or to resume decoding after a seek.
+
+source
+   data fed to the decoder or encoder; see ``OUTPUT``.
+
+source height
+   height in pixels for given source resolution; relevant to encoders only.
+
+source resolution
+   resolution in pixels of source frames being source to the encoder and
+   subject to further cropping to the bounds of visible resolution; relevant to
+   encoders only.
+
+source width
+   width in pixels for given source resolution; relevant to encoders only.
+
+SPS
+   Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
+
+stream metadata
+   additional (non-visual) information contained inside encoded bitstream;
+   for example: coded resolution, visible resolution, codec profile.
+
+visible height
+   height for given visible resolution; display height.
+
+visible resolution
+   stream resolution of the visible picture, in pixels, to be used for
+   display purposes; must be smaller or equal to coded resolution;
+   display resolution.
+
+visible width
+   width for given visible resolution; display width.
+
+State machine
+=============
+
+.. kernel-render:: DOT
+   :alt: DOT digraph of decoder state machine
+   :caption: Decoder state machine
+
+   digraph decoder_state_machine {
+       node [shape = doublecircle, label="Decoding"] Decoding;
+
+       node [shape = circle, label="Initialization"] Initialization;
+       node [shape = circle, label="Capture\nsetup"] CaptureSetup;
+       node [shape = circle, label="Dynamic\nresolution\nchange"] ResChange;
+       node [shape = circle, label="Stopped"] Stopped;
+       node [shape = circle, label="Drain"] Drain;
+       node [shape = circle, label="Seek"] Seek;
+       node [shape = circle, label="End of stream"] EoS;
+
+       node [shape = point]; qi
+       qi -> Initialization [ label = "open()" ];
+
+       Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
+
+       CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
+
+       Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
+       Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
+       Decoding -> EoS [ label = "EoS mark\nin the stream" ];
+       Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
+       Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
+       Decoding -> Decoding;
+
+       ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
+       ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
+
+       EoS -> Drain [ label = "Implicit\ndrain" ];
+
+       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
+       Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
+
+       Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
+       Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
+
+       Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
+       Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
+   }
+
+Querying capabilities
+=====================
+
+1. To enumerate the set of coded formats supported by the decoder, the
+   client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
+
+   * The full set of supported formats will be returned, regardless of the
+     format set on ``CAPTURE``.
+
+2. To enumerate the set of supported raw formats, the client may call
+   :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
+
+   * Only the formats supported for the format currently active on ``OUTPUT``
+     will be returned.
+
+   * In order to enumerate raw formats supported by a given coded format,
+     the client must first set that coded format on ``OUTPUT`` and then
+     enumerate formats on ``CAPTURE``.
+
+3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
+   resolutions for a given format, passing desired pixel format in
+   :c:type:`v4l2_frmsizeenum` ``pixel_format``.
+
+   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
+     format will include all possible coded resolutions supported by the
+     decoder for given coded pixel format.
+
+   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
+     will include all possible frame buffer resolutions supported by the
+     decoder for given raw pixel format and the coded format currently set on
+     ``OUTPUT``.
+
+4. Supported profiles and levels for the coded format currently set on
+   ``OUTPUT``, if applicable, may be queried using their respective controls
+   via :c:func:`VIDIOC_QUERYCTRL`.
+
+Initialization
+==============
+
+1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
+
+   * **Required fields:**
+
+     ``type``
+         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+     ``pixelformat``
+         a coded pixel format.
+
+     ``width``, ``height``
+         coded resolution of the stream; required only if it cannot be parsed
+         from the stream for the given coded format; otherwise the decoder will
+         use this resolution as a placeholder resolution that will likely change
+         as soon as it can parse the actual coded resolution from the stream.
+
+     ``sizeimage``
+         desired size of ``OUTPUT`` buffers; the decoder may adjust it to
+         match hardware requirements.
+
+     other fields
+         follow standard semantics.
+
+   * **Return fields:**
+
+     ``sizeimage``
+         adjusted size of ``OUTPUT`` buffers.
+
+   * The ``CAPTURE`` format will be updated with an appropriate frame buffer
+     resolution instantly based on the width and height returned by
+     :c:func:`VIDIOC_S_FMT`.
+     However, for coded formats that include stream resolution information,
+     after the decoder is done parsing the information from the stream, it will
+     update the ``CAPTURE`` format with new values and signal a source change
+     event, regardless of whether they match the values set by the client or
+     not.
+
+   .. important::
+
+      Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
+      format. How the new ``CAPTURE`` format is determined is up to the decoder
+      and the client must ensure it matches its needs afterwards.
+
+2.  Allocate source (bitstream) buffers via :c:func:`VIDIOC_REQBUFS` on
+    ``OUTPUT``.
+
+    * **Required fields:**
+
+      ``count``
+          requested number of buffers to allocate; greater than zero.
+
+      ``type``
+          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+      ``memory``
+          follows standard semantics.
+
+    * **Return fields:**
+
+      ``count``
+          the actual number of buffers allocated.
+
+    .. warning::
+
+       The actual number of allocated buffers may differ from the ``count``
+       given. The client must check the updated value of ``count`` after the
+       call returns.
+
+    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
+    used to have more control over buffer allocation.
+
+    * **Required fields:**
+
+      ``count``
+          requested number of buffers to allocate; greater than zero.
+
+      ``type``
+          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+      ``memory``
+          follows standard semantics.
+
+      ``format``
+          follows standard semantics.
+
+    * **Return fields:**
+
+      ``count``
+          adjusted to the number of allocated buffers.
+
+    .. warning::
+
+       The actual number of allocated buffers may differ from the ``count``
+       given. The client must check the updated value of ``count`` after the
+       call returns.
+
+3.  Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
+
+4.  **This step only applies to coded formats that contain resolution information
+    in the stream.** Continue queuing/dequeuing bitstream buffers to/from the
+    ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
+    buffers will be processed and returned to the client in order, until
+    required metadata to configure the ``CAPTURE`` queue are found. This is
+    indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
+    ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
+
+    * It is not an error if the first buffer does not contain enough data for
+      this to occur. Processing of the buffers will continue as long as more
+      data is needed.
+
+    * If data in a buffer that triggers the event is required to decode the
+      first frame, it will not be returned to the client, until the
+      initialization sequence completes and the frame is decoded.
+
+    * If the client has not set the coded resolution of the stream on its own,
+      calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
+      :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
+      queue will not return the real values for the stream until a
+      ``V4L2_EVENT_SOURCE_CHANGE`` event is signaled.
+
+    .. important::
+
+       Any client query issued after the decoder queues the event will return
+       values applying to the just parsed stream, including queue formats,
+       selection rectangles and controls.
+
+    .. note::
+
+       A client capable of acquiring stream parameters from the bitstream on
+       its own may attempt to set the width and height of the ``OUTPUT`` format
+       to non-zero values matching the coded size of the stream, skip this step
+       and continue with the `Capture setup` sequence. However, it must not
+       rely on any driver queries regarding stream parameters, such as
+       selection rectangles and controls, since the decoder has not parsed them
+       from the stream yet. If the values configured by the client do not match
+       those parsed by the decoder, a `Dynamic resolution change` will be
+       triggered to reconfigure them.
+
+    .. note::
+
+       No decoded frames are produced during this phase.
+
+5.  Continue with the `Capture setup` sequence.
+
+Capture setup
+=============
+
+1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
+    destination buffers parsed/decoded from the bitstream.
+
+    * **Required fields:**
+
+      ``type``
+          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+    * **Return fields:**
+
+      ``width``, ``height``
+          frame buffer resolution for the decoded frames.
+
+      ``pixelformat``
+          pixel format for decoded frames.
+
+      ``num_planes`` (for _MPLANE ``type`` only)
+          number of planes for pixelformat.
+
+      ``sizeimage``, ``bytesperline``
+          as per standard semantics; matching frame buffer format.
+
+    .. note::
+
+       The value of ``pixelformat`` may be any pixel format supported by the
+       decoder for the current stream. The decoder should choose a
+       preferred/optimal format for the default configuration. For example, a
+       YUV format may be preferred over an RGB format if an additional
+       conversion step would be required for the latter.
+
+2.  **Optional.** Acquire the visible resolution via
+    :c:func:`VIDIOC_G_SELECTION`.
+
+    * **Required fields:**
+
+      ``type``
+          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+      ``target``
+          set to ``V4L2_SEL_TGT_COMPOSE``.
+
+    * **Return fields:**
+
+      ``r.left``, ``r.top``, ``r.width``, ``r.height``
+          the visible rectangle; it must fit within the frame buffer resolution
+          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
+
+    * The following selection targets are supported on ``CAPTURE``:
+
+      ``V4L2_SEL_TGT_CROP_BOUNDS``
+          corresponds to the coded resolution of the stream.
+
+      ``V4L2_SEL_TGT_CROP_DEFAULT``
+          the rectangle covering the part of the ``CAPTURE`` buffer that
+          contains meaningful picture data (visible area); width and height
+          will be equal to the visible resolution of the stream.
+
+      ``V4L2_SEL_TGT_CROP``
+          the rectangle within the coded resolution to be output to
+          ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
+          hardware without additional compose/scaling capabilities.
+
+      ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
+          the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
+          frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
+          hardware does not support compose/scaling.
+
+      ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
+          equal to ``V4L2_SEL_TGT_CROP``.
+
+      ``V4L2_SEL_TGT_COMPOSE``
+          the rectangle inside a ``CAPTURE`` buffer into which the cropped
+          frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
+          read-only on hardware without additional compose/scaling capabilities.
+
+      ``V4L2_SEL_TGT_COMPOSE_PADDED``
+          the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
+          hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
+          write padding pixels.
+
+    .. warning::
+
+       The values are guaranteed to be meaningful only after the decoder
+       successfully parses the stream metadata. The client must not rely on the
+       query before that happens.
+
+3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
+    the ``CAPTURE`` queue. Once the stream information is parsed and known, the
+    client may use this ioctl to discover which raw formats are supported for
+    given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
+
+    .. important::
+
+       The decoder will return only formats supported for the currently
+       established coded format, as per the ``OUTPUT`` format and/or stream
+       metadata parsed in this initialization sequence, even if more formats
+       may be supported by the decoder in general. In other words, the set
+       returned will be a subset of the initial query mentioned in the
+       `Querying capabilities` section.
+
+       For example, a decoder may support YUV and RGB formats for resolutions
+       1920x1088 and lower, but only YUV for higher resolutions (due to
+       hardware limitations). After parsing a resolution of 1920x1088 or lower,
+       :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
+       but after parsing resolution higher than 1920x1088, the decoder will not
+       return RGB, unsupported for this resolution.
+
+       However, subsequent resolution change event triggered after
+       discovering a resolution change within the same stream may switch
+       the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
+       would return RGB formats again in that case.
+
+4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
+    ``CAPTURE`` queue. The client may choose a different format than
+    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
+
+    * **Required fields:**
+
+      ``type``
+          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+      ``pixelformat``
+          a raw pixel format.
+
+   * Setting the ``CAPTURE`` format will reset the compose selection rectangles
+     to their default values, based on the new resolution, as described in the
+     previous step.
+
+5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
+   the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
+   scaling capabilities.
+
+   * **Required fields:**
+
+     ``type``
+         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+     ``target``
+         set to ``V4L2_SEL_TGT_COMPOSE``.
+
+     ``r.left``, ``r.top``, ``r.width``, ``r.height``
+         the rectangle inside a ``CAPTURE`` buffer into which the cropped
+         frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
+         read-only on hardware without additional compose/scaling capabilities.
+
+   * **Return fields:**
+
+     ``r.left``, ``r.top``, ``r.width``, ``r.height``
+         the visible rectangle; it must fit within the frame buffer resolution
+         returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
+
+   .. warning::
+
+      The decoder may adjust the compose rectangle to the nearest
+      supported one to meet codec and hardware requirements. The client needs
+      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
+
+6.  If all the following conditions are met, the client may resume the decoding
+    instantly:
+
+    * ``sizeimage`` of the new format (determined in previous steps) is less
+      than or equal to the size of currently allocated buffers,
+
+    * the number of buffers currently allocated is greater than or equal to the
+      minimum number of buffers acquired in previous steps. To fulfill this
+      requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
+      buffers.
+
+    In that case, the remaining steps do not apply and the client may resume
+    the decoding by one of the following actions:
+
+    * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
+      with the ``V4L2_DEC_CMD_START`` command,
+
+    * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
+      on the ``CAPTURE`` queue.
+
+    However, if the client intends to change the buffer set, to lower
+    memory usage or for any other reasons, it may be achieved by following
+    the steps below.
+
+7.  **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
+    buffers on the ``CAPTURE`` queue until a buffer marked with the
+    ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
+
+8.  **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
+    on the ``CAPTURE`` queue to stop streaming.
+
+    .. warning::
+
+       The ``OUTPUT`` queue must remain streaming. Calling
+       :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
+       seek.
+
+9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
+    buffers using :c:func:`VIDIOC_REQBUFS`.
+
+    * **Required fields:**
+
+      ``count``
+          set to 0.
+
+      ``type``
+          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+      ``memory``
+          follows standard semantics.
+
+10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
+    ``CAPTURE`` queue.
+
+    * **Required fields:**
+
+      ``count``
+          requested number of buffers to allocate; greater than zero.
+
+      ``type``
+          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+      ``memory``
+          follows standard semantics.
+
+    * **Return fields:**
+
+      ``count``
+          actual number of buffers allocated.
+
+    .. warning::
+
+       The actual number of allocated buffers may differ from the ``count``
+       given. The client must check the updated value of ``count`` after the
+       call returns.
+
+    .. note::
+
+       To allocate more than the minimum number of buffers (for pipeline
+       depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
+       control to get the minimum number of buffers required, and pass the
+       obtained value plus the number of additional buffers needed in the
+       ``count`` field to :c:func:`VIDIOC_REQBUFS`.
+
+    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
+    used to have more control over buffer allocation. For example, by
+    allocating buffers larger than the current ``CAPTURE`` format, future
+    resolution changes can be accommodated.
+
+    * **Required fields:**
+
+      ``count``
+          requested number of buffers to allocate; greater than zero.
+
+      ``type``
+          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+      ``memory``
+          follows standard semantics.
+
+      ``format``
+          a format representing the maximum framebuffer resolution to be
+          accommodated by newly allocated buffers.
+
+    * **Return fields:**
+
+      ``count``
+          adjusted to the number of allocated buffers.
+
+    .. warning::
+
+        The actual number of allocated buffers may differ from the ``count``
+        given. The client must check the updated value of ``count`` after the
+        call returns.
+
+    .. note::
+
+       To allocate buffers for a format different than parsed from the stream
+       metadata, the client must proceed as follows, before the metadata
+       parsing is initiated:
+
+       * set width and height of the ``OUTPUT`` format to desired coded resolution to
+         let the decoder configure the ``CAPTURE`` format appropriately,
+
+       * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
+         until this step.
+
+       The format obtained in the query may be then used with
+       :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
+
+11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
+    frames.
+
+Decoding
+========
+
+This state is reached after the `Capture setup` sequence finishes successfully.
+In this state, the client queues and dequeues buffers to both queues via
+:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
+semantics.
+
+The content of the source ``OUTPUT`` buffers depends on the active coded pixel
+format and may be affected by codec-specific extended controls, as stated in
+the documentation of each format.
+
+Both queues operate independently, following the standard behavior of V4L2
+buffer queues and memory-to-memory devices. In addition, the order of decoded
+frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
+coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
+format, e.g. frame reordering.
+
+The client must not assume any direct relationship between ``CAPTURE``
+and ``OUTPUT`` buffers and any specific timing of buffers becoming
+available to dequeue. Specifically:
+
+* a buffer queued to ``OUTPUT`` may result in no buffers being produced
+  on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
+  metadata syntax structures are present in it),
+
+* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
+  on ``CAPTURE`` (if the encoded data contained more than one frame, or if
+  returning a decoded frame allowed the decoder to return a frame that
+  preceded it in decode, but succeeded it in the display order),
+
+* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
+  ``CAPTURE`` later into decode process, and/or after processing further
+  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
+  reordering is used,
+
+* buffers may become available on the ``CAPTURE`` queue without additional
+  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
+  ``OUTPUT`` buffers queued in the past whose decoding results are only
+  available at later time, due to specifics of the decoding process.
+
+.. note::
+
+   To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
+   originated from, the client can set the ``timestamp`` field of the
+   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
+   ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
+   will have their ``timestamp`` field set to the same value when dequeued.
+
+   In addition to the straightforward case of one ``OUTPUT`` buffer producing
+   one ``CAPTURE`` buffer, the following cases are defined:
+
+   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
+     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
+
+   * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
+     the ``OUTPUT`` buffer queued last will be copied.
+
+   * the decoding order differs from the display order (i.e. the ``CAPTURE``
+     buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
+     timestamps will not retain the order of ``OUTPUT`` timestamps.
+
+During the decoding, the decoder may initiate one of the special sequences, as
+listed below. The sequences will result in the decoder returning all the
+``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
+before the sequence started. Last of the buffers will have the
+``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
+must check if there is any pending event and:
+
+* if a ``V4L2_EVENT_SOURCE_CHANGE`` event is pending, the `Dynamic resolution
+  change` sequence needs to be followed,
+
+* if a ``V4L2_EVENT_EOS`` event is pending, the `End of stream` sequence needs
+  to be followed.
+
+Some of the sequences can be intermixed with each other and need to be handled
+as they happen. The exact operation is documented for each sequence.
+
+Should a decoding error occur, it will be reported to the client with the level
+of details depending on the decoder capabilities. Specifically:
+
+* the CAPTURE buffer that contains the results of the failed decode operation
+  will be returned with the V4L2_BUF_FLAG_ERROR flag set,
+
+* if the decoder is able to precisely report the OUTPUT buffer that triggered
+  the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
+  set.
+
+In case of a fatal failure that does not allow the decoding to continue, any
+further operations on corresponding decoder file handle will return the -EIO
+error code. The client may close the file handle and open a new one, or
+alternatively reinitialize the instance by stopping streaming on both queues,
+releasing all buffers and performing the Initialization sequence again.
+
+Seek
+====
+
+Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
+The seek does not require any specific operation on the ``CAPTURE`` queue, but
+it may be affected as per normal decoder operation.
+
+1. Stop the ``OUTPUT`` queue to begin the seek sequence via
+   :c:func:`VIDIOC_STREAMOFF`.
+
+   * **Required fields:**
+
+     ``type``
+         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+   * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
+     treated as returned to the client (following standard semantics).
+
+2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`
+
+   * **Required fields:**
+
+     ``type``
+         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+   * The decoder will start accepting new source bitstream buffers after the
+     call returns.
+
+3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
+   queue until a suitable resume point is found.
+
+   .. note::
+
+      There is no requirement to begin queuing coded data starting exactly
+      from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
+      buffers will be processed and returned to the client until a suitable
+      resume point is found.  While looking for a resume point, the decoder
+      should not produce any decoded frames into ``CAPTURE`` buffers.
+
+      Some hardware is known to mishandle seeks to a non-resume point. Such an
+      operation may result in an unspecified number of corrupted decoded frames
+      being made available on the ``CAPTURE`` queue. Drivers must ensure that
+      no fatal decoding errors or crashes occur, and implement any necessary
+      handling and workarounds for hardware issues related to seek operations.
+
+   .. warning::
+
+      In case of the H.264/HEVC codec, the client must take care not to seek
+      over a change of SPS/PPS. Even though the target frame could be a
+      keyframe, the stale SPS/PPS inside decoder state would lead to undefined
+      results when decoding. Although the decoder must handle that case without
+      a crash or a fatal decode error, the client must not expect a sensible
+      decode output.
+
+      If the hardware can detect such corrupted decoded frames, then
+      corresponding buffers will be returned to the client with the
+      V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
+      description of decode error reporting.
+
+4. After a resume point is found, the decoder will start returning ``CAPTURE``
+   buffers containing decoded frames.
+
+.. important::
+
+   A seek may result in the `Dynamic resolution change` sequence being
+   initiated, due to the seek target having decoding parameters different from
+   the part of the stream decoded before the seek. The sequence must be handled
+   as per normal decoder operation.
+
+.. warning::
+
+   It is not specified when the ``CAPTURE`` queue starts producing buffers
+   containing decoded data from the ``OUTPUT`` buffers queued after the seek,
+   as it operates independently from the ``OUTPUT`` queue.
+
+   The decoder may return a number of remaining ``CAPTURE`` buffers containing
+   decoded frames originating from the ``OUTPUT`` buffers queued before the
+   seek sequence is performed.
+
+   The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
+   ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
+   queued before the seek sequence may have matching ``CAPTURE`` buffers
+   produced.  For example, given the sequence of operations on the
+   ``OUTPUT`` queue:
+
+     QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
+
+   any of the following results on the ``CAPTURE`` queue is allowed:
+
+     {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}.
+
+   To determine the CAPTURE buffer containing the first decoded frame after the
+   seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
+   buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
+   decoder.
+
+.. note::
+
+   To achieve instantaneous seek, the client may restart streaming on the
+   ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
+
+Dynamic resolution change
+=========================
+
+Streams that include resolution metadata in the bitstream may require switching
+to a different resolution during the decoding.
+
+The sequence starts when the decoder detects a coded frame with one or more of
+the following parameters different from those previously established (and
+reflected by corresponding queries):
+
+* coded resolution (``OUTPUT`` width and height),
+
+* visible resolution (selection rectangles),
+
+* the minimum number of buffers needed for decoding.
+
+Whenever that happens, the decoder must proceed as follows:
+
+1.  After encountering a resolution change in the stream, the decoder sends a
+    ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
+    ``V4L2_EVENT_SRC_CH_RESOLUTION``.
+
+    .. important::
+
+       Any client query issued after the decoder queues the event will return
+       values applying to the stream after the resolution change, including
+       queue formats, selection rectangles and controls.
+
+2.  The decoder will then process and decode all remaining buffers from before
+    the resolution change point.
+
+    * The last buffer from before the change must be marked with the
+      ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
+
+    .. warning::
+
+       The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
+       = 0) and in that case it must be ignored by the client, as it does not
+       contain a decoded frame.
+
+    .. note::
+
+       Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
+       with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
+       :c:func:`VIDIOC_DQBUF`.
+
+The client must continue the sequence as described below to continue the
+decoding process.
+
+1.  Dequeue the source change event.
+
+    .. important::
+
+       A source change triggers an implicit decoder drain, similar to the
+       explicit `Drain` sequence. The decoder is stopped after it completes.
+       The decoding process must be resumed with either a pair of calls to
+       :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
+       ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
+       ``V4L2_DEC_CMD_START`` command.
+
+2.  Continue with the `Capture setup` sequence.
+
+.. note::
+
+   During the resolution change sequence, the ``OUTPUT`` queue must remain
+   streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
+   abort the sequence and initiate a seek.
+
+   In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
+   queue and this remains true for the duration of the entire resolution change
+   sequence as well.
+
+   The client should, for best performance and simplicity, keep queuing/dequeuing
+   buffers to/from the ``OUTPUT`` queue even while processing this sequence.
+
+Drain
+=====
+
+To ensure that all queued ``OUTPUT`` buffers have been processed and related
+``CAPTURE`` buffers are given to the client, the client must follow the drain
+sequence described below. After the drain sequence ends, the client has
+received all decoded frames for all ``OUTPUT`` buffers queued before the
+sequence was started.
+
+1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
+
+   * **Required fields:**
+
+     ``cmd``
+         set to ``V4L2_DEC_CMD_STOP``.
+
+     ``flags``
+         set to 0.
+
+     ``pts``
+         set to 0.
+
+   .. warning::
+
+      The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
+      queues are streaming. For compatibility reasons, the call to
+      :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
+      not streaming, but at the same time it will not initiate the `Drain`
+      sequence and so the steps described below would not be applicable.
+
+2. Any ``OUTPUT`` buffers queued by the client before the
+   :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
+   normal. The client must continue to handle both queues independently,
+   similarly to normal decode operation. This includes:
+
+   * handling any operations triggered as a result of processing those buffers,
+     such as the `Dynamic resolution change` sequence, before continuing with
+     the drain sequence,
+
+   * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
+     ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
+
+     .. warning::
+
+        The last buffer may be empty (with :c:type:`v4l2_buffer`
+        ``bytesused`` = 0) and in that case it must be ignored by the client,
+        as it does not contain a decoded frame.
+
+     .. note::
+
+        Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
+        marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
+        :c:func:`VIDIOC_DQBUF`.
+
+   * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
+     before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
+
+   * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
+
+   .. note::
+
+      For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
+      event when the last frame has been decoded and all frames are ready to be
+      dequeued. It is a deprecated behavior and the client must not rely on it.
+      The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
+
+3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
+   are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
+   stopped and it will accept, but not process, any newly queued ``OUTPUT``
+   buffers until the client issues any of the following operations:
+
+   * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
+     operation normally, with all the state from before the drain,
+
+   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
+     ``CAPTURE`` queue - the decoder will resume the operation normally,
+     however any ``CAPTURE`` buffers still in the queue will be returned to the
+     client,
+
+   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
+     ``OUTPUT`` queue - any pending source buffers will be returned to the
+     client and the `Seek` sequence will be triggered.
+
+.. note::
+
+   Once the drain sequence is initiated, the client needs to drive it to
+   completion, as described by the steps above, unless it aborts the process by
+   issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
+   queues.  The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
+   ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
+   will fail with -EBUSY error code if attempted.
+
+   Although mandatory, the availability of decoder commands may be queried
+   using :c:func:`VIDIOC_TRY_DECODER_CMD`.
+
+End of stream
+=============
+
+If the decoder encounters an end of stream marking in the stream, the decoder
+will initiate the `Drain` sequence, which the client must handle as described
+above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
+
+Commit points
+=============
+
+Setting formats and allocating buffers trigger changes in the behavior of the
+decoder.
+
+1. Setting the format on the ``OUTPUT`` queue may change the set of formats
+   supported/advertised on the ``CAPTURE`` queue. In particular, it also means
+   that the ``CAPTURE`` format may be reset and the client must not rely on the
+   previously set format being preserved.
+
+2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
+   supported for the current ``OUTPUT`` format.
+
+3. Setting the format on the ``CAPTURE`` queue does not change the list of
+   formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
+   format that is not supported for the currently selected ``OUTPUT`` format
+   will result in the decoder adjusting the requested ``CAPTURE`` format to a
+   supported one.
+
+4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
+   supported coded formats, irrespectively of the current ``CAPTURE`` format.
+
+5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
+   the client must not change the format on the ``OUTPUT`` queue. Drivers will
+   return the -EBUSY error code for any such format change attempt.
+
+To summarize, setting formats and allocation must always start with the
+``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
+set of supported formats for the ``CAPTURE`` queue.
diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
index 67a980818dc8..caa05f5f6380 100644
--- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
+++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
@@ -39,4 +39,10 @@ file handle is visible through another file handle).
 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
diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
index 71eebfc6d853..caf14e440447 100644
--- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
@@ -39,6 +39,11 @@ Single-planar format structure
 	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.
diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
index 004ec00db6bd..97015b9b40b8 100644
--- a/Documentation/media/uapi/v4l/v4l2.rst
+++ b/Documentation/media/uapi/v4l/v4l2.rst
@@ -60,6 +60,10 @@ Authors, in alphabetical order:
 
   - 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.
@@ -68,6 +72,10 @@ Authors, in alphabetical order:
 
   - 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.
@@ -92,7 +100,7 @@ Authors, in alphabetical order:
 
   - 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.
diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
index ccf83b05afa7..57f0066f4cff 100644
--- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
+++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
@@ -56,14 +56,16 @@ The ``cmd`` field must contain the command code. Some commands use the
 
 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}|
@@ -167,26 +169,32 @@ introduced in Linux 3.3.
 	``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
@@ -209,6 +217,11 @@ 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.
 
+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.
 
-- 
2.20.1

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Nicolas Dufresne]

[-- Attachment #1: Type: text/plain, Size: 57804 bytes --]

Hi Hans,

I went through it, and I think we are close to ready. Unfortunately, I
believe the SOURCE_CHANGE event is still under specified. There was a
post recently to try and add a new flag for changes in color space
which is not included here. We are also missing a workflow for changes
that don't affect the allocation but will affect the rendering on a
display (like colorimetry). Userspace needs to know at which frames
these parameter changes in order to signal that to the following
processing block. I think we must have a plane for this.

Another aspect, I'd like if we could relax a bit the bits about dynamic
resolutions, making some space for the "static resolution" cases.
Something to keep in mind, these "static resolution" HW might not be
able to inform userspace of the display size of the picture, we should
check with Maxime what happens with the Amlogic.

Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> From: Tomasz Figa <tfiga@chromium.org>
> 
> Due to complexity of the video decoding process, the V4L2 drivers of
> stateful decoder hardware require specific sequences of V4L2 API calls
> to be followed. These include capability enumeration, initialization,
> decoding, seek, pause, dynamic resolution change, drain and end of
> stream.
> 
> Specifics of the above have been discussed during Media Workshops at
> LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
> Conference Europe 2014 in Düsseldorf. The de facto Codec API that
> originated at those events was later implemented by the drivers we already
> have merged in mainline, such as s5p-mfc or coda.
> 
> The only thing missing was the real specification included as a part of
> Linux Media documentation. Fix it now and document the decoder part of
> the Codec API.
> 
> Signed-off-by: Tomasz Figa <tfiga@chromium.org>
> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> ---
>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
>  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
>  5 files changed, 1132 insertions(+), 16 deletions(-)
>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> 
> diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst
> new file mode 100644
> index 000000000000..b106f2d97c48
> --- /dev/null
> +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
> @@ -0,0 +1,1084 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _decoder:
> +
> +*************************************************
> +Memory-to-memory Stateful Video Decoder Interface
> +*************************************************
> +
> +A stateful video decoder takes complete chunks of the bitstream (e.g. Annex-B
> +H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in

(minor, may ignore)
This isn't very precise, do we expect to document this per-format ? I
think we should maybe say "a complete frame of the bitstream", that
being said, I think stateful CODEC should be allowed to implement the
per-slice/per-frame control we are adding to stateless CODEC. Maybe
something like "documented complete chunks of bitstream" ?

> +display order. The decoder is expected not to require any additional information
> +from the client to process these buffers.
> +
> +Performing software parsing, processing etc. of the stream in the driver in
> +order to support this interface is strongly discouraged. In case such
> +operations are needed, use of the Stateless Video Decoder Interface (in
> +development) is strongly advised.
> +
> +Conventions and notation used in this document
> +==============================================
> +
> +1. The general V4L2 API rules apply if not specified in this document
> +   otherwise.
> +
> +2. The meaning of words "must", "may", "should", etc. is as per `RFC
> +   2119 <https://tools.ietf.org/html/rfc2119>`_.
> +
> +3. All steps not marked "optional" are required.
> +
> +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
> +   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
> +   unless specified otherwise.
> +
> +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
> +   used interchangeably with multi-planar API, unless specified otherwise,
> +   depending on decoder capabilities and following the general V4L2 guidelines.
> +
> +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
> +   [0..2]: i = 0, 1, 2.
> +
> +7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
> +   queue containing data that resulted from processing buffer A.
> +
> +.. _decoder-glossary:
> +
> +Glossary
> +========
> +
> +CAPTURE
> +   the destination buffer queue; for decoders, the queue of buffers containing
> +   decoded frames; for encoders, the queue of buffers containing an encoded
> +   bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
> +   ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
> +   into ``CAPTURE`` buffers.
> +
> +client
> +   the application communicating with the decoder or encoder implementing
> +   this interface.
> +
> +coded format
> +   encoded/compressed video bitstream format (e.g. H.264, VP8, etc.); see
> +   also: raw format.
> +
> +coded height
> +   height for given coded resolution.
> +
> +coded resolution
> +   stream resolution in pixels aligned to codec and hardware requirements;
> +   typically visible resolution rounded up to full macroblocks;
> +   see also: visible resolution.
> +
> +coded width
> +   width for given coded resolution.
> +
> +decode order
> +   the order in which frames are decoded; may differ from display order if the
> +   coded format includes a feature of frame reordering; for decoders,
> +   ``OUTPUT`` buffers must be queued by the client in decode order; for
> +   encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
> +
> +destination
> +   data resulting from the decode process; see ``CAPTURE``.
> +
> +display order
> +   the order in which frames must be displayed; for encoders, ``OUTPUT``
> +   buffers must be queued by the client in display order; for decoders,
> +   ``CAPTURE`` buffers must be returned by the decoder in display order.
> +
> +DPB
> +   Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
> +   raw frame available for reference in further decoding steps.
> +
> +EOS
> +   end of stream.
> +
> +IDR
> +   Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
> +   stream, which clears the list of earlier reference frames (DPBs).
> +
> +keyframe
> +   an encoded frame that does not reference frames decoded earlier, i.e.
> +   can be decoded fully on its own.
> +
> +macroblock
> +   a processing unit in image and video compression formats based on linear
> +   block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
> +   popular codecs the size is 16x16 samples (pixels).
> +
> +OUTPUT
> +   the source buffer queue; for decoders, the queue of buffers containing
> +   an encoded bitstream; for encoders, the queue of buffers containing raw
> +   frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
> +   ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
> +   from ``OUTPUT`` buffers.
> +
> +PPS
> +   Picture Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> +
> +raw format
> +   uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
> +
> +resume point
> +   a point in the bitstream from which decoding may start/continue, without
> +   any previous state/data present, e.g.: a keyframe (VP8/VP9) or
> +   SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
> +   of a new stream, or to resume decoding after a seek.
> +
> +source
> +   data fed to the decoder or encoder; see ``OUTPUT``.
> +
> +source height
> +   height in pixels for given source resolution; relevant to encoders only.
> +
> +source resolution
> +   resolution in pixels of source frames being source to the encoder and
> +   subject to further cropping to the bounds of visible resolution; relevant to
> +   encoders only.
> +
> +source width
> +   width in pixels for given source resolution; relevant to encoders only.
> +
> +SPS
> +   Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> +
> +stream metadata
> +   additional (non-visual) information contained inside encoded bitstream;
> +   for example: coded resolution, visible resolution, codec profile.
> +
> +visible height
> +   height for given visible resolution; display height.
> +
> +visible resolution
> +   stream resolution of the visible picture, in pixels, to be used for
> +   display purposes; must be smaller or equal to coded resolution;
> +   display resolution.
> +
> +visible width
> +   width for given visible resolution; display width.
> +
> +State machine
> +=============
> +
> +.. kernel-render:: DOT
> +   :alt: DOT digraph of decoder state machine
> +   :caption: Decoder state machine
> +
> +   digraph decoder_state_machine {
> +       node [shape = doublecircle, label="Decoding"] Decoding;
> +
> +       node [shape = circle, label="Initialization"] Initialization;
> +       node [shape = circle, label="Capture\nsetup"] CaptureSetup;
> +       node [shape = circle, label="Dynamic\nresolution\nchange"] ResChange;
> +       node [shape = circle, label="Stopped"] Stopped;
> +       node [shape = circle, label="Drain"] Drain;
> +       node [shape = circle, label="Seek"] Seek;
> +       node [shape = circle, label="End of stream"] EoS;
> +
> +       node [shape = point]; qi
> +       qi -> Initialization [ label = "open()" ];
> +
> +       Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> +
> +       CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
> +
> +       Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
> +       Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
> +       Decoding -> EoS [ label = "EoS mark\nin the stream" ];
> +       Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> +       Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
> +       Decoding -> Decoding;
> +
> +       ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> +       ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> +
> +       EoS -> Drain [ label = "Implicit\ndrain" ];
> +
> +       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
> +       Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> +
> +       Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
> +       Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
> +
> +       Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
> +       Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> +   }
> +
> +Querying capabilities
> +=====================
> +
> +1. To enumerate the set of coded formats supported by the decoder, the
> +   client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
> +
> +   * The full set of supported formats will be returned, regardless of the
> +     format set on ``CAPTURE``.
> +
> +2. To enumerate the set of supported raw formats, the client may call
> +   :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
> +
> +   * Only the formats supported for the format currently active on ``OUTPUT``
> +     will be returned.
> +
> +   * In order to enumerate raw formats supported by a given coded format,
> +     the client must first set that coded format on ``OUTPUT`` and then
> +     enumerate formats on ``CAPTURE``.
> +
> +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
> +   resolutions for a given format, passing desired pixel format in
> +   :c:type:`v4l2_frmsizeenum` ``pixel_format``.
> +
> +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
> +     format will include all possible coded resolutions supported by the
> +     decoder for given coded pixel format.
> +
> +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
> +     will include all possible frame buffer resolutions supported by the
> +     decoder for given raw pixel format and the coded format currently set on
> +     ``OUTPUT``.
> +
> +4. Supported profiles and levels for the coded format currently set on
> +   ``OUTPUT``, if applicable, may be queried using their respective controls
> +   via :c:func:`VIDIOC_QUERYCTRL`.
> +
> +Initialization
> +==============
> +
> +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
> +
> +   * **Required fields:**
> +
> +     ``type``
> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> +
> +     ``pixelformat``
> +         a coded pixel format.
> +
> +     ``width``, ``height``
> +         coded resolution of the stream; required only if it cannot be parsed
> +         from the stream for the given coded format; otherwise the decoder will
> +         use this resolution as a placeholder resolution that will likely change
> +         as soon as it can parse the actual coded resolution from the stream.
> +
> +     ``sizeimage``
> +         desired size of ``OUTPUT`` buffers; the decoder may adjust it to
> +         match hardware requirements.
> +
> +     other fields
> +         follow standard semantics.
> +
> +   * **Return fields:**
> +
> +     ``sizeimage``
> +         adjusted size of ``OUTPUT`` buffers.
> +
> +   * The ``CAPTURE`` format will be updated with an appropriate frame buffer
> +     resolution instantly based on the width and height returned by
> +     :c:func:`VIDIOC_S_FMT`.
> +     However, for coded formats that include stream resolution information,
> +     after the decoder is done parsing the information from the stream, it will
> +     update the ``CAPTURE`` format with new values and signal a source change
> +     event, regardless of whether they match the values set by the client or
> +     not.
> +
> +   .. important::
> +
> +      Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
> +      format. How the new ``CAPTURE`` format is determined is up to the decoder
> +      and the client must ensure it matches its needs afterwards.
> +
> +2.  Allocate source (bitstream) buffers via :c:func:`VIDIOC_REQBUFS` on
> +    ``OUTPUT``.
> +
> +    * **Required fields:**
> +
> +      ``count``
> +          requested number of buffers to allocate; greater than zero.
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> +
> +      ``memory``
> +          follows standard semantics.
> +
> +    * **Return fields:**
> +
> +      ``count``
> +          the actual number of buffers allocated.
> +
> +    .. warning::
> +
> +       The actual number of allocated buffers may differ from the ``count``
> +       given. The client must check the updated value of ``count`` after the
> +       call returns.
> +
> +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
> +    used to have more control over buffer allocation.
> +
> +    * **Required fields:**
> +
> +      ``count``
> +          requested number of buffers to allocate; greater than zero.
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> +
> +      ``memory``
> +          follows standard semantics.
> +
> +      ``format``
> +          follows standard semantics.
> +
> +    * **Return fields:**
> +
> +      ``count``
> +          adjusted to the number of allocated buffers.
> +
> +    .. warning::
> +
> +       The actual number of allocated buffers may differ from the ``count``
> +       given. The client must check the updated value of ``count`` after the
> +       call returns.
> +
> +3.  Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
> +
> +4.  **This step only applies to coded formats that contain resolution information
> +    in the stream.** Continue queuing/dequeuing bitstream buffers to/from the
> +    ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
> +    buffers will be processed and returned to the client in order, until
> +    required metadata to configure the ``CAPTURE`` queue are found. This is
> +    indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
> +    ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> +
> +    * It is not an error if the first buffer does not contain enough data for
> +      this to occur. Processing of the buffers will continue as long as more
> +      data is needed.
> +
> +    * If data in a buffer that triggers the event is required to decode the
> +      first frame, it will not be returned to the client, until the
> +      initialization sequence completes and the frame is decoded.
> +
> +    * If the client has not set the coded resolution of the stream on its own,
> +      calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
> +      :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
> +      queue will not return the real values for the stream until a
> +      ``V4L2_EVENT_SOURCE_CHANGE`` event is signaled.
> +
> +    .. important::
> +
> +       Any client query issued after the decoder queues the event will return
> +       values applying to the just parsed stream, including queue formats,
> +       selection rectangles and controls.
> +
> +    .. note::
> +
> +       A client capable of acquiring stream parameters from the bitstream on
> +       its own may attempt to set the width and height of the ``OUTPUT`` format
> +       to non-zero values matching the coded size of the stream, skip this step
> +       and continue with the `Capture setup` sequence. However, it must not
> +       rely on any driver queries regarding stream parameters, such as
> +       selection rectangles and controls, since the decoder has not parsed them
> +       from the stream yet. If the values configured by the client do not match
> +       those parsed by the decoder, a `Dynamic resolution change` will be
> +       triggered to reconfigure them.
> +
> +    .. note::
> +
> +       No decoded frames are produced during this phase.
> +
> +5.  Continue with the `Capture setup` sequence.
> +
> +Capture setup
> +=============
> +
> +1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
> +    destination buffers parsed/decoded from the bitstream.
> +
> +    * **Required fields:**
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +    * **Return fields:**
> +
> +      ``width``, ``height``
> +          frame buffer resolution for the decoded frames.
> +
> +      ``pixelformat``
> +          pixel format for decoded frames.
> +
> +      ``num_planes`` (for _MPLANE ``type`` only)
> +          number of planes for pixelformat.
> +
> +      ``sizeimage``, ``bytesperline``
> +          as per standard semantics; matching frame buffer format.
> +
> +    .. note::
> +
> +       The value of ``pixelformat`` may be any pixel format supported by the
> +       decoder for the current stream. The decoder should choose a
> +       preferred/optimal format for the default configuration. For example, a
> +       YUV format may be preferred over an RGB format if an additional
> +       conversion step would be required for the latter.
> +
> +2.  **Optional.** Acquire the visible resolution via
> +    :c:func:`VIDIOC_G_SELECTION`.
> +
> +    * **Required fields:**
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``target``
> +          set to ``V4L2_SEL_TGT_COMPOSE``.
> +
> +    * **Return fields:**
> +
> +      ``r.left``, ``r.top``, ``r.width``, ``r.height``
> +          the visible rectangle; it must fit within the frame buffer resolution
> +          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> +
> +    * The following selection targets are supported on ``CAPTURE``:
> +
> +      ``V4L2_SEL_TGT_CROP_BOUNDS``
> +          corresponds to the coded resolution of the stream.
> +
> +      ``V4L2_SEL_TGT_CROP_DEFAULT``
> +          the rectangle covering the part of the ``CAPTURE`` buffer that
> +          contains meaningful picture data (visible area); width and height
> +          will be equal to the visible resolution of the stream.
> +
> +      ``V4L2_SEL_TGT_CROP``
> +          the rectangle within the coded resolution to be output to
> +          ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
> +          hardware without additional compose/scaling capabilities.
> +
> +      ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
> +          the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
> +          frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
> +          hardware does not support compose/scaling.
> +
> +      ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
> +          equal to ``V4L2_SEL_TGT_CROP``.
> +
> +      ``V4L2_SEL_TGT_COMPOSE``
> +          the rectangle inside a ``CAPTURE`` buffer into which the cropped
> +          frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> +          read-only on hardware without additional compose/scaling capabilities.
> +
> +      ``V4L2_SEL_TGT_COMPOSE_PADDED``
> +          the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
> +          hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
> +          write padding pixels.
> +
> +    .. warning::
> +
> +       The values are guaranteed to be meaningful only after the decoder
> +       successfully parses the stream metadata. The client must not rely on the
> +       query before that happens.
> +
> +3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
> +    the ``CAPTURE`` queue. Once the stream information is parsed and known, the
> +    client may use this ioctl to discover which raw formats are supported for
> +    given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
> +
> +    .. important::
> +
> +       The decoder will return only formats supported for the currently
> +       established coded format, as per the ``OUTPUT`` format and/or stream
> +       metadata parsed in this initialization sequence, even if more formats
> +       may be supported by the decoder in general. In other words, the set
> +       returned will be a subset of the initial query mentioned in the
> +       `Querying capabilities` section.
> +
> +       For example, a decoder may support YUV and RGB formats for resolutions
> +       1920x1088 and lower, but only YUV for higher resolutions (due to
> +       hardware limitations). After parsing a resolution of 1920x1088 or lower,
> +       :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
> +       but after parsing resolution higher than 1920x1088, the decoder will not
> +       return RGB, unsupported for this resolution.
> +
> +       However, subsequent resolution change event triggered after
> +       discovering a resolution change within the same stream may switch
> +       the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
> +       would return RGB formats again in that case.
> +
> +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
> +    ``CAPTURE`` queue. The client may choose a different format than
> +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
> +
> +    * **Required fields:**
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``pixelformat``
> +          a raw pixel format.
> +
> +   * Setting the ``CAPTURE`` format will reset the compose selection rectangles
> +     to their default values, based on the new resolution, as described in the
> +     previous step.
> +
> +5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
> +   the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
> +   scaling capabilities.
> +
> +   * **Required fields:**
> +
> +     ``type``
> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +     ``target``
> +         set to ``V4L2_SEL_TGT_COMPOSE``.
> +
> +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> +         the rectangle inside a ``CAPTURE`` buffer into which the cropped
> +         frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> +         read-only on hardware without additional compose/scaling capabilities.
> +
> +   * **Return fields:**
> +
> +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> +         the visible rectangle; it must fit within the frame buffer resolution
> +         returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> +
> +   .. warning::
> +
> +      The decoder may adjust the compose rectangle to the nearest
> +      supported one to meet codec and hardware requirements. The client needs
> +      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
> +
> +6.  If all the following conditions are met, the client may resume the decoding
> +    instantly:
> +
> +    * ``sizeimage`` of the new format (determined in previous steps) is less
> +      than or equal to the size of currently allocated buffers,
> +
> +    * the number of buffers currently allocated is greater than or equal to the
> +      minimum number of buffers acquired in previous steps. To fulfill this
> +      requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
> +      buffers.
> +
> +    In that case, the remaining steps do not apply and the client may resume
> +    the decoding by one of the following actions:
> +
> +    * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
> +      with the ``V4L2_DEC_CMD_START`` command,
> +
> +    * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
> +      on the ``CAPTURE`` queue.
> +
> +    However, if the client intends to change the buffer set, to lower
> +    memory usage or for any other reasons, it may be achieved by following
> +    the steps below.
> +
> +7.  **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
> +    buffers on the ``CAPTURE`` queue until a buffer marked with the
> +    ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
> +
> +8.  **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
> +    on the ``CAPTURE`` queue to stop streaming.
> +
> +    .. warning::
> +
> +       The ``OUTPUT`` queue must remain streaming. Calling
> +       :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
> +       seek.
> +
> +9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
> +    buffers using :c:func:`VIDIOC_REQBUFS`.
> +
> +    * **Required fields:**
> +
> +      ``count``
> +          set to 0.
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``memory``
> +          follows standard semantics.
> +
> +10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
> +    ``CAPTURE`` queue.
> +
> +    * **Required fields:**
> +
> +      ``count``
> +          requested number of buffers to allocate; greater than zero.
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``memory``
> +          follows standard semantics.
> +
> +    * **Return fields:**
> +
> +      ``count``
> +          actual number of buffers allocated.
> +
> +    .. warning::
> +
> +       The actual number of allocated buffers may differ from the ``count``
> +       given. The client must check the updated value of ``count`` after the
> +       call returns.
> +
> +    .. note::
> +
> +       To allocate more than the minimum number of buffers (for pipeline
> +       depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
> +       control to get the minimum number of buffers required, and pass the
> +       obtained value plus the number of additional buffers needed in the
> +       ``count`` field to :c:func:`VIDIOC_REQBUFS`.
> +
> +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
> +    used to have more control over buffer allocation. For example, by
> +    allocating buffers larger than the current ``CAPTURE`` format, future
> +    resolution changes can be accommodated.
> +
> +    * **Required fields:**
> +
> +      ``count``
> +          requested number of buffers to allocate; greater than zero.
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``memory``
> +          follows standard semantics.
> +
> +      ``format``
> +          a format representing the maximum framebuffer resolution to be
> +          accommodated by newly allocated buffers.
> +
> +    * **Return fields:**
> +
> +      ``count``
> +          adjusted to the number of allocated buffers.
> +
> +    .. warning::
> +
> +        The actual number of allocated buffers may differ from the ``count``
> +        given. The client must check the updated value of ``count`` after the
> +        call returns.
> +
> +    .. note::
> +
> +       To allocate buffers for a format different than parsed from the stream
> +       metadata, the client must proceed as follows, before the metadata
> +       parsing is initiated:
> +
> +       * set width and height of the ``OUTPUT`` format to desired coded resolution to
> +         let the decoder configure the ``CAPTURE`` format appropriately,
> +
> +       * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
> +         until this step.
> +
> +       The format obtained in the query may be then used with
> +       :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
> +
> +11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
> +    frames.
> +
> +Decoding
> +========
> +
> +This state is reached after the `Capture setup` sequence finishes successfully.
> +In this state, the client queues and dequeues buffers to both queues via
> +:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
> +semantics.
> +
> +The content of the source ``OUTPUT`` buffers depends on the active coded pixel
> +format and may be affected by codec-specific extended controls, as stated in
> +the documentation of each format.
> +
> +Both queues operate independently, following the standard behavior of V4L2
> +buffer queues and memory-to-memory devices. In addition, the order of decoded
> +frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
> +coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
> +format, e.g. frame reordering.
> +
> +The client must not assume any direct relationship between ``CAPTURE``
> +and ``OUTPUT`` buffers and any specific timing of buffers becoming
> +available to dequeue. Specifically:
> +
> +* a buffer queued to ``OUTPUT`` may result in no buffers being produced
> +  on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
> +  metadata syntax structures are present in it),
> +
> +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
> +  on ``CAPTURE`` (if the encoded data contained more than one frame, or if
> +  returning a decoded frame allowed the decoder to return a frame that
> +  preceded it in decode, but succeeded it in the display order),
> +
> +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
> +  ``CAPTURE`` later into decode process, and/or after processing further
> +  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
> +  reordering is used,
> +
> +* buffers may become available on the ``CAPTURE`` queue without additional
> +  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
> +  ``OUTPUT`` buffers queued in the past whose decoding results are only
> +  available at later time, due to specifics of the decoding process.
> +
> +.. note::
> +
> +   To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
> +   originated from, the client can set the ``timestamp`` field of the
> +   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
> +   ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
> +   will have their ``timestamp`` field set to the same value when dequeued.
> +
> +   In addition to the straightforward case of one ``OUTPUT`` buffer producing
> +   one ``CAPTURE`` buffer, the following cases are defined:
> +
> +   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
> +     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
> +
> +   * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
> +     the ``OUTPUT`` buffer queued last will be copied.
> +
> +   * the decoding order differs from the display order (i.e. the ``CAPTURE``
> +     buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
> +     timestamps will not retain the order of ``OUTPUT`` timestamps.
> +
> +During the decoding, the decoder may initiate one of the special sequences, as
> +listed below. The sequences will result in the decoder returning all the
> +``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
> +before the sequence started. Last of the buffers will have the
> +``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
> +must check if there is any pending event and:
> +
> +* if a ``V4L2_EVENT_SOURCE_CHANGE`` event is pending, the `Dynamic resolution
> +  change` sequence needs to be followed,
> +
> +* if a ``V4L2_EVENT_EOS`` event is pending, the `End of stream` sequence needs
> +  to be followed.
> +
> +Some of the sequences can be intermixed with each other and need to be handled
> +as they happen. The exact operation is documented for each sequence.
> +
> +Should a decoding error occur, it will be reported to the client with the level
> +of details depending on the decoder capabilities. Specifically:
> +
> +* the CAPTURE buffer that contains the results of the failed decode operation
> +  will be returned with the V4L2_BUF_FLAG_ERROR flag set,
> +
> +* if the decoder is able to precisely report the OUTPUT buffer that triggered
> +  the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
> +  set.
> +
> +In case of a fatal failure that does not allow the decoding to continue, any
> +further operations on corresponding decoder file handle will return the -EIO
> +error code. The client may close the file handle and open a new one, or
> +alternatively reinitialize the instance by stopping streaming on both queues,
> +releasing all buffers and performing the Initialization sequence again.
> +
> +Seek
> +====
> +
> +Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
> +The seek does not require any specific operation on the ``CAPTURE`` queue, but
> +it may be affected as per normal decoder operation.
> +
> +1. Stop the ``OUTPUT`` queue to begin the seek sequence via
> +   :c:func:`VIDIOC_STREAMOFF`.
> +
> +   * **Required fields:**
> +
> +     ``type``
> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> +
> +   * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
> +     treated as returned to the client (following standard semantics).
> +
> +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`
> +
> +   * **Required fields:**
> +
> +     ``type``
> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> +
> +   * The decoder will start accepting new source bitstream buffers after the
> +     call returns.
> +
> +3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
> +   queue until a suitable resume point is found.
> +
> +   .. note::
> +
> +      There is no requirement to begin queuing coded data starting exactly
> +      from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
> +      buffers will be processed and returned to the client until a suitable
> +      resume point is found.  While looking for a resume point, the decoder
> +      should not produce any decoded frames into ``CAPTURE`` buffers.
> +
> +      Some hardware is known to mishandle seeks to a non-resume point. Such an
> +      operation may result in an unspecified number of corrupted decoded frames
> +      being made available on the ``CAPTURE`` queue. Drivers must ensure that
> +      no fatal decoding errors or crashes occur, and implement any necessary
> +      handling and workarounds for hardware issues related to seek operations.
> +
> +   .. warning::
> +
> +      In case of the H.264/HEVC codec, the client must take care not to seek
> +      over a change of SPS/PPS. Even though the target frame could be a
> +      keyframe, the stale SPS/PPS inside decoder state would lead to undefined
> +      results when decoding. Although the decoder must handle that case without
> +      a crash or a fatal decode error, the client must not expect a sensible
> +      decode output.
> +
> +      If the hardware can detect such corrupted decoded frames, then
> +      corresponding buffers will be returned to the client with the
> +      V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
> +      description of decode error reporting.
> +
> +4. After a resume point is found, the decoder will start returning ``CAPTURE``
> +   buffers containing decoded frames.
> +
> +.. important::
> +
> +   A seek may result in the `Dynamic resolution change` sequence being
> +   initiated, due to the seek target having decoding parameters different from
> +   the part of the stream decoded before the seek. The sequence must be handled
> +   as per normal decoder operation.
> +
> +.. warning::
> +
> +   It is not specified when the ``CAPTURE`` queue starts producing buffers
> +   containing decoded data from the ``OUTPUT`` buffers queued after the seek,
> +   as it operates independently from the ``OUTPUT`` queue.
> +
> +   The decoder may return a number of remaining ``CAPTURE`` buffers containing
> +   decoded frames originating from the ``OUTPUT`` buffers queued before the
> +   seek sequence is performed.
> +
> +   The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
> +   ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
> +   queued before the seek sequence may have matching ``CAPTURE`` buffers
> +   produced.  For example, given the sequence of operations on the
> +   ``OUTPUT`` queue:
> +
> +     QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
> +
> +   any of the following results on the ``CAPTURE`` queue is allowed:
> +
> +     {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}.
> +
> +   To determine the CAPTURE buffer containing the first decoded frame after the
> +   seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
> +   buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
> +   decoder.
> +
> +.. note::
> +
> +   To achieve instantaneous seek, the client may restart streaming on the
> +   ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
> +
> +Dynamic resolution change
> +=========================
> +
> +Streams that include resolution metadata in the bitstream may require switching
> +to a different resolution during the decoding.
> +
> +The sequence starts when the decoder detects a coded frame with one or more of
> +the following parameters different from those previously established (and
> +reflected by corresponding queries):
> +
> +* coded resolution (``OUTPUT`` width and height),
> +
> +* visible resolution (selection rectangles),
> +
> +* the minimum number of buffers needed for decoding.
> +
> +Whenever that happens, the decoder must proceed as follows:
> +
> +1.  After encountering a resolution change in the stream, the decoder sends a
> +    ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
> +    ``V4L2_EVENT_SRC_CH_RESOLUTION``.

What about a format changes that does now affect the resolution, like a
pixel format change ? Also, what about changes that don't require a
reallocation ? Like a change in the colorimetry parameters ? I don't
think the spec need to initially cover it all, but we need to make sure
there is a mechanism for userspace to know at which frames to read back
the new format (G_FMT). Maybe we need both an event and a buffer flag
to mark it ?

> +
> +    .. important::
> +
> +       Any client query issued after the decoder queues the event will return
> +       values applying to the stream after the resolution change, including
> +       queue formats, selection rectangles and controls.
> +
> +2.  The decoder will then process and decode all remaining buffers from before
> +    the resolution change point.
> +
> +    * The last buffer from before the change must be marked with the
> +      ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
> +
> +    .. warning::
> +
> +       The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
> +       = 0) and in that case it must be ignored by the client, as it does not
> +       contain a decoded frame.
> +
> +    .. note::
> +
> +       Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
> +       with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
> +       :c:func:`VIDIOC_DQBUF`.
> +
> +The client must continue the sequence as described below to continue the
> +decoding process.
> +
> +1.  Dequeue the source change event.
> +
> +    .. important::
> +
> +       A source change triggers an implicit decoder drain, similar to the
> +       explicit `Drain` sequence. The decoder is stopped after it completes.
> +       The decoding process must be resumed with either a pair of calls to
> +       :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> +       ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
> +       ``V4L2_DEC_CMD_START`` command.
> +
> +2.  Continue with the `Capture setup` sequence.
> +
> +.. note::
> +
> +   During the resolution change sequence, the ``OUTPUT`` queue must remain
> +   streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
> +   abort the sequence and initiate a seek.
> +
> +   In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
> +   queue and this remains true for the duration of the entire resolution change
> +   sequence as well.
> +
> +   The client should, for best performance and simplicity, keep queuing/dequeuing
> +   buffers to/from the ``OUTPUT`` queue even while processing this sequence.
> +
> +Drain
> +=====
> +
> +To ensure that all queued ``OUTPUT`` buffers have been processed and related
> +``CAPTURE`` buffers are given to the client, the client must follow the drain
> +sequence described below. After the drain sequence ends, the client has
> +received all decoded frames for all ``OUTPUT`` buffers queued before the
> +sequence was started.
> +
> +1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
> +
> +   * **Required fields:**
> +
> +     ``cmd``
> +         set to ``V4L2_DEC_CMD_STOP``.
> +
> +     ``flags``
> +         set to 0.
> +
> +     ``pts``
> +         set to 0.
> +
> +   .. warning::
> +
> +      The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
> +      queues are streaming. For compatibility reasons, the call to
> +      :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
> +      not streaming, but at the same time it will not initiate the `Drain`
> +      sequence and so the steps described below would not be applicable.
> +
> +2. Any ``OUTPUT`` buffers queued by the client before the
> +   :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
> +   normal. The client must continue to handle both queues independently,
> +   similarly to normal decode operation. This includes:
> +
> +   * handling any operations triggered as a result of processing those buffers,
> +     such as the `Dynamic resolution change` sequence, before continuing with
> +     the drain sequence,
> +
> +   * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
> +     ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
> +
> +     .. warning::
> +
> +        The last buffer may be empty (with :c:type:`v4l2_buffer`
> +        ``bytesused`` = 0) and in that case it must be ignored by the client,
> +        as it does not contain a decoded frame.
> +
> +     .. note::
> +
> +        Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
> +        marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
> +        :c:func:`VIDIOC_DQBUF`.
> +
> +   * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
> +     before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
> +
> +   * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
> +
> +   .. note::
> +
> +      For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
> +      event when the last frame has been decoded and all frames are ready to be
> +      dequeued. It is a deprecated behavior and the client must not rely on it.
> +      The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
> +
> +3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
> +   are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
> +   stopped and it will accept, but not process, any newly queued ``OUTPUT``
> +   buffers until the client issues any of the following operations:
> +
> +   * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
> +     operation normally, with all the state from before the drain,
> +
> +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> +     ``CAPTURE`` queue - the decoder will resume the operation normally,
> +     however any ``CAPTURE`` buffers still in the queue will be returned to the
> +     client,
> +
> +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> +     ``OUTPUT`` queue - any pending source buffers will be returned to the
> +     client and the `Seek` sequence will be triggered.
> +
> +.. note::
> +
> +   Once the drain sequence is initiated, the client needs to drive it to
> +   completion, as described by the steps above, unless it aborts the process by
> +   issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
> +   queues.  The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
> +   ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
> +   will fail with -EBUSY error code if attempted.
> +
> +   Although mandatory, the availability of decoder commands may be queried
> +   using :c:func:`VIDIOC_TRY_DECODER_CMD`.
> +
> +End of stream
> +=============
> +
> +If the decoder encounters an end of stream marking in the stream, the decoder
> +will initiate the `Drain` sequence, which the client must handle as described
> +above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
> +
> +Commit points
> +=============
> +
> +Setting formats and allocating buffers trigger changes in the behavior of the
> +decoder.
> +
> +1. Setting the format on the ``OUTPUT`` queue may change the set of formats
> +   supported/advertised on the ``CAPTURE`` queue. In particular, it also means
> +   that the ``CAPTURE`` format may be reset and the client must not rely on the
> +   previously set format being preserved.
> +
> +2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
> +   supported for the current ``OUTPUT`` format.
> +
> +3. Setting the format on the ``CAPTURE`` queue does not change the list of
> +   formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
> +   format that is not supported for the currently selected ``OUTPUT`` format
> +   will result in the decoder adjusting the requested ``CAPTURE`` format to a
> +   supported one.
> +
> +4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
> +   supported coded formats, irrespectively of the current ``CAPTURE`` format.
> +
> +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
> +   the client must not change the format on the ``OUTPUT`` queue. Drivers will
> +   return the -EBUSY error code for any such format change attempt.
> +
> +To summarize, setting formats and allocation must always start with the
> +``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
> +set of supported formats for the ``CAPTURE`` queue.
> diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> index 67a980818dc8..caa05f5f6380 100644
> --- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
> +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> @@ -39,4 +39,10 @@ file handle is visible through another file handle).
>  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
> diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> index 71eebfc6d853..caf14e440447 100644
> --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> @@ -39,6 +39,11 @@ Single-planar format structure
>  	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.
> diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> index 004ec00db6bd..97015b9b40b8 100644
> --- a/Documentation/media/uapi/v4l/v4l2.rst
> +++ b/Documentation/media/uapi/v4l/v4l2.rst
> @@ -60,6 +60,10 @@ Authors, in alphabetical order:
>  
>    - 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.
> @@ -68,6 +72,10 @@ Authors, in alphabetical order:
>  
>    - 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.
> @@ -92,7 +100,7 @@ Authors, in alphabetical order:
>  
>    - 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.
> diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> index ccf83b05afa7..57f0066f4cff 100644
> --- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> @@ -56,14 +56,16 @@ The ``cmd`` field must contain the command code. Some commands use the
>  
>  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}|
> @@ -167,26 +169,32 @@ introduced in Linux 3.3.
>  	``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
> @@ -209,6 +217,11 @@ 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.
>  
> +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.
>  

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Hans Verkuil]

On 6/10/19 9:54 PM, Nicolas Dufresne wrote:
> Hi Hans,
> 
> I went through it, and I think we are close to ready. Unfortunately, I
> believe the SOURCE_CHANGE event is still under specified. There was a
> post recently to try and add a new flag for changes in color space
> which is not included here. We are also missing a workflow for changes
> that don't affect the allocation but will affect the rendering on a
> display (like colorimetry). Userspace needs to know at which frames
> these parameter changes in order to signal that to the following
> processing block. I think we must have a plane for this.

Yes, we need a new flag for the SOURCE_CHANGE event to indicate colorimetry
changes. That's actually useful for e.g. HDMI receivers as well.

But I don't see why that should make much of a change to the spec: you still
have to drain the capture queue, the only difference is that you don't need
to reallocate buffers, you can just restart the decoder.

My intention was to get this spec in first, then extend it once we have a new
colorimetry change flag.

> 
> Another aspect, I'd like if we could relax a bit the bits about dynamic
> resolutions, making some space for the "static resolution" cases.
> Something to keep in mind, these "static resolution" HW might not be
> able to inform userspace of the display size of the picture, we should
> check with Maxime what happens with the Amlogic.

I've asked him about that in another email thread:

https://www.mail-archive.com/linux-media@vger.kernel.org/msg147652.html

Maxime, related to that: can the amlogic detect midstream colorimetry
changes? Or is that also impossible?

> 
> Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
>> From: Tomasz Figa <tfiga@chromium.org>
>>
>> Due to complexity of the video decoding process, the V4L2 drivers of
>> stateful decoder hardware require specific sequences of V4L2 API calls
>> to be followed. These include capability enumeration, initialization,
>> decoding, seek, pause, dynamic resolution change, drain and end of
>> stream.
>>
>> Specifics of the above have been discussed during Media Workshops at
>> LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
>> Conference Europe 2014 in Düsseldorf. The de facto Codec API that
>> originated at those events was later implemented by the drivers we already
>> have merged in mainline, such as s5p-mfc or coda.
>>
>> The only thing missing was the real specification included as a part of
>> Linux Media documentation. Fix it now and document the decoder part of
>> the Codec API.
>>
>> Signed-off-by: Tomasz Figa <tfiga@chromium.org>
>> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
>> ---
>>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
>>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
>>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
>>  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
>>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
>>  5 files changed, 1132 insertions(+), 16 deletions(-)
>>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>>
>> diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst
>> new file mode 100644
>> index 000000000000..b106f2d97c48
>> --- /dev/null
>> +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
>> @@ -0,0 +1,1084 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +.. _decoder:
>> +
>> +*************************************************
>> +Memory-to-memory Stateful Video Decoder Interface
>> +*************************************************
>> +
>> +A stateful video decoder takes complete chunks of the bitstream (e.g. Annex-B
>> +H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
> 
> (minor, may ignore)
> This isn't very precise, do we expect to document this per-format ? I
> think we should maybe say "a complete frame of the bitstream", that
> being said, I think stateful CODEC should be allowed to implement the
> per-slice/per-frame control we are adding to stateless CODEC. Maybe
> something like "documented complete chunks of bitstream" ?
> 
>> +display order. The decoder is expected not to require any additional information
>> +from the client to process these buffers.
>> +
>> +Performing software parsing, processing etc. of the stream in the driver in
>> +order to support this interface is strongly discouraged. In case such
>> +operations are needed, use of the Stateless Video Decoder Interface (in
>> +development) is strongly advised.
>> +
>> +Conventions and notation used in this document
>> +==============================================
>> +
>> +1. The general V4L2 API rules apply if not specified in this document
>> +   otherwise.
>> +
>> +2. The meaning of words "must", "may", "should", etc. is as per `RFC
>> +   2119 <https://tools.ietf.org/html/rfc2119>`_.
>> +
>> +3. All steps not marked "optional" are required.
>> +
>> +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
>> +   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
>> +   unless specified otherwise.
>> +
>> +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
>> +   used interchangeably with multi-planar API, unless specified otherwise,
>> +   depending on decoder capabilities and following the general V4L2 guidelines.
>> +
>> +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
>> +   [0..2]: i = 0, 1, 2.
>> +
>> +7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
>> +   queue containing data that resulted from processing buffer A.
>> +
>> +.. _decoder-glossary:
>> +
>> +Glossary
>> +========
>> +
>> +CAPTURE
>> +   the destination buffer queue; for decoders, the queue of buffers containing
>> +   decoded frames; for encoders, the queue of buffers containing an encoded
>> +   bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
>> +   ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
>> +   into ``CAPTURE`` buffers.
>> +
>> +client
>> +   the application communicating with the decoder or encoder implementing
>> +   this interface.
>> +
>> +coded format
>> +   encoded/compressed video bitstream format (e.g. H.264, VP8, etc.); see
>> +   also: raw format.
>> +
>> +coded height
>> +   height for given coded resolution.
>> +
>> +coded resolution
>> +   stream resolution in pixels aligned to codec and hardware requirements;
>> +   typically visible resolution rounded up to full macroblocks;
>> +   see also: visible resolution.
>> +
>> +coded width
>> +   width for given coded resolution.
>> +
>> +decode order
>> +   the order in which frames are decoded; may differ from display order if the
>> +   coded format includes a feature of frame reordering; for decoders,
>> +   ``OUTPUT`` buffers must be queued by the client in decode order; for
>> +   encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
>> +
>> +destination
>> +   data resulting from the decode process; see ``CAPTURE``.
>> +
>> +display order
>> +   the order in which frames must be displayed; for encoders, ``OUTPUT``
>> +   buffers must be queued by the client in display order; for decoders,
>> +   ``CAPTURE`` buffers must be returned by the decoder in display order.
>> +
>> +DPB
>> +   Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
>> +   raw frame available for reference in further decoding steps.
>> +
>> +EOS
>> +   end of stream.
>> +
>> +IDR
>> +   Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
>> +   stream, which clears the list of earlier reference frames (DPBs).
>> +
>> +keyframe
>> +   an encoded frame that does not reference frames decoded earlier, i.e.
>> +   can be decoded fully on its own.
>> +
>> +macroblock
>> +   a processing unit in image and video compression formats based on linear
>> +   block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
>> +   popular codecs the size is 16x16 samples (pixels).
>> +
>> +OUTPUT
>> +   the source buffer queue; for decoders, the queue of buffers containing
>> +   an encoded bitstream; for encoders, the queue of buffers containing raw
>> +   frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
>> +   ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
>> +   from ``OUTPUT`` buffers.
>> +
>> +PPS
>> +   Picture Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
>> +
>> +raw format
>> +   uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
>> +
>> +resume point
>> +   a point in the bitstream from which decoding may start/continue, without
>> +   any previous state/data present, e.g.: a keyframe (VP8/VP9) or
>> +   SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
>> +   of a new stream, or to resume decoding after a seek.
>> +
>> +source
>> +   data fed to the decoder or encoder; see ``OUTPUT``.
>> +
>> +source height
>> +   height in pixels for given source resolution; relevant to encoders only.
>> +
>> +source resolution
>> +   resolution in pixels of source frames being source to the encoder and
>> +   subject to further cropping to the bounds of visible resolution; relevant to
>> +   encoders only.
>> +
>> +source width
>> +   width in pixels for given source resolution; relevant to encoders only.
>> +
>> +SPS
>> +   Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
>> +
>> +stream metadata
>> +   additional (non-visual) information contained inside encoded bitstream;
>> +   for example: coded resolution, visible resolution, codec profile.
>> +
>> +visible height
>> +   height for given visible resolution; display height.
>> +
>> +visible resolution
>> +   stream resolution of the visible picture, in pixels, to be used for
>> +   display purposes; must be smaller or equal to coded resolution;
>> +   display resolution.
>> +
>> +visible width
>> +   width for given visible resolution; display width.
>> +
>> +State machine
>> +=============
>> +
>> +.. kernel-render:: DOT
>> +   :alt: DOT digraph of decoder state machine
>> +   :caption: Decoder state machine
>> +
>> +   digraph decoder_state_machine {
>> +       node [shape = doublecircle, label="Decoding"] Decoding;
>> +
>> +       node [shape = circle, label="Initialization"] Initialization;
>> +       node [shape = circle, label="Capture\nsetup"] CaptureSetup;
>> +       node [shape = circle, label="Dynamic\nresolution\nchange"] ResChange;
>> +       node [shape = circle, label="Stopped"] Stopped;
>> +       node [shape = circle, label="Drain"] Drain;
>> +       node [shape = circle, label="Seek"] Seek;
>> +       node [shape = circle, label="End of stream"] EoS;
>> +
>> +       node [shape = point]; qi
>> +       qi -> Initialization [ label = "open()" ];
>> +
>> +       Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
>> +
>> +       CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
>> +
>> +       Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
>> +       Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
>> +       Decoding -> EoS [ label = "EoS mark\nin the stream" ];
>> +       Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
>> +       Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
>> +       Decoding -> Decoding;
>> +
>> +       ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
>> +       ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
>> +
>> +       EoS -> Drain [ label = "Implicit\ndrain" ];
>> +
>> +       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
>> +       Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
>> +
>> +       Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
>> +       Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
>> +
>> +       Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
>> +       Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
>> +   }
>> +
>> +Querying capabilities
>> +=====================
>> +
>> +1. To enumerate the set of coded formats supported by the decoder, the
>> +   client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
>> +
>> +   * The full set of supported formats will be returned, regardless of the
>> +     format set on ``CAPTURE``.
>> +
>> +2. To enumerate the set of supported raw formats, the client may call
>> +   :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
>> +
>> +   * Only the formats supported for the format currently active on ``OUTPUT``
>> +     will be returned.
>> +
>> +   * In order to enumerate raw formats supported by a given coded format,
>> +     the client must first set that coded format on ``OUTPUT`` and then
>> +     enumerate formats on ``CAPTURE``.
>> +
>> +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
>> +   resolutions for a given format, passing desired pixel format in
>> +   :c:type:`v4l2_frmsizeenum` ``pixel_format``.
>> +
>> +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
>> +     format will include all possible coded resolutions supported by the
>> +     decoder for given coded pixel format.
>> +
>> +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
>> +     will include all possible frame buffer resolutions supported by the
>> +     decoder for given raw pixel format and the coded format currently set on
>> +     ``OUTPUT``.
>> +
>> +4. Supported profiles and levels for the coded format currently set on
>> +   ``OUTPUT``, if applicable, may be queried using their respective controls
>> +   via :c:func:`VIDIOC_QUERYCTRL`.
>> +
>> +Initialization
>> +==============
>> +
>> +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
>> +
>> +   * **Required fields:**
>> +
>> +     ``type``
>> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
>> +
>> +     ``pixelformat``
>> +         a coded pixel format.
>> +
>> +     ``width``, ``height``
>> +         coded resolution of the stream; required only if it cannot be parsed
>> +         from the stream for the given coded format; otherwise the decoder will
>> +         use this resolution as a placeholder resolution that will likely change
>> +         as soon as it can parse the actual coded resolution from the stream.
>> +
>> +     ``sizeimage``
>> +         desired size of ``OUTPUT`` buffers; the decoder may adjust it to
>> +         match hardware requirements.
>> +
>> +     other fields
>> +         follow standard semantics.
>> +
>> +   * **Return fields:**
>> +
>> +     ``sizeimage``
>> +         adjusted size of ``OUTPUT`` buffers.
>> +
>> +   * The ``CAPTURE`` format will be updated with an appropriate frame buffer
>> +     resolution instantly based on the width and height returned by
>> +     :c:func:`VIDIOC_S_FMT`.
>> +     However, for coded formats that include stream resolution information,
>> +     after the decoder is done parsing the information from the stream, it will
>> +     update the ``CAPTURE`` format with new values and signal a source change
>> +     event, regardless of whether they match the values set by the client or
>> +     not.
>> +
>> +   .. important::
>> +
>> +      Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
>> +      format. How the new ``CAPTURE`` format is determined is up to the decoder
>> +      and the client must ensure it matches its needs afterwards.
>> +
>> +2.  Allocate source (bitstream) buffers via :c:func:`VIDIOC_REQBUFS` on
>> +    ``OUTPUT``.
>> +
>> +    * **Required fields:**
>> +
>> +      ``count``
>> +          requested number of buffers to allocate; greater than zero.
>> +
>> +      ``type``
>> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
>> +
>> +      ``memory``
>> +          follows standard semantics.
>> +
>> +    * **Return fields:**
>> +
>> +      ``count``
>> +          the actual number of buffers allocated.
>> +
>> +    .. warning::
>> +
>> +       The actual number of allocated buffers may differ from the ``count``
>> +       given. The client must check the updated value of ``count`` after the
>> +       call returns.
>> +
>> +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
>> +    used to have more control over buffer allocation.
>> +
>> +    * **Required fields:**
>> +
>> +      ``count``
>> +          requested number of buffers to allocate; greater than zero.
>> +
>> +      ``type``
>> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
>> +
>> +      ``memory``
>> +          follows standard semantics.
>> +
>> +      ``format``
>> +          follows standard semantics.
>> +
>> +    * **Return fields:**
>> +
>> +      ``count``
>> +          adjusted to the number of allocated buffers.
>> +
>> +    .. warning::
>> +
>> +       The actual number of allocated buffers may differ from the ``count``
>> +       given. The client must check the updated value of ``count`` after the
>> +       call returns.
>> +
>> +3.  Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
>> +
>> +4.  **This step only applies to coded formats that contain resolution information
>> +    in the stream.** Continue queuing/dequeuing bitstream buffers to/from the
>> +    ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
>> +    buffers will be processed and returned to the client in order, until
>> +    required metadata to configure the ``CAPTURE`` queue are found. This is
>> +    indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
>> +    ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
>> +
>> +    * It is not an error if the first buffer does not contain enough data for
>> +      this to occur. Processing of the buffers will continue as long as more
>> +      data is needed.
>> +
>> +    * If data in a buffer that triggers the event is required to decode the
>> +      first frame, it will not be returned to the client, until the
>> +      initialization sequence completes and the frame is decoded.
>> +
>> +    * If the client has not set the coded resolution of the stream on its own,
>> +      calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
>> +      :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
>> +      queue will not return the real values for the stream until a
>> +      ``V4L2_EVENT_SOURCE_CHANGE`` event is signaled.
>> +
>> +    .. important::
>> +
>> +       Any client query issued after the decoder queues the event will return
>> +       values applying to the just parsed stream, including queue formats,
>> +       selection rectangles and controls.
>> +
>> +    .. note::
>> +
>> +       A client capable of acquiring stream parameters from the bitstream on
>> +       its own may attempt to set the width and height of the ``OUTPUT`` format
>> +       to non-zero values matching the coded size of the stream, skip this step
>> +       and continue with the `Capture setup` sequence. However, it must not
>> +       rely on any driver queries regarding stream parameters, such as
>> +       selection rectangles and controls, since the decoder has not parsed them
>> +       from the stream yet. If the values configured by the client do not match
>> +       those parsed by the decoder, a `Dynamic resolution change` will be
>> +       triggered to reconfigure them.
>> +
>> +    .. note::
>> +
>> +       No decoded frames are produced during this phase.
>> +
>> +5.  Continue with the `Capture setup` sequence.
>> +
>> +Capture setup
>> +=============
>> +
>> +1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
>> +    destination buffers parsed/decoded from the bitstream.
>> +
>> +    * **Required fields:**
>> +
>> +      ``type``
>> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
>> +
>> +    * **Return fields:**
>> +
>> +      ``width``, ``height``
>> +          frame buffer resolution for the decoded frames.
>> +
>> +      ``pixelformat``
>> +          pixel format for decoded frames.
>> +
>> +      ``num_planes`` (for _MPLANE ``type`` only)
>> +          number of planes for pixelformat.
>> +
>> +      ``sizeimage``, ``bytesperline``
>> +          as per standard semantics; matching frame buffer format.
>> +
>> +    .. note::
>> +
>> +       The value of ``pixelformat`` may be any pixel format supported by the
>> +       decoder for the current stream. The decoder should choose a
>> +       preferred/optimal format for the default configuration. For example, a
>> +       YUV format may be preferred over an RGB format if an additional
>> +       conversion step would be required for the latter.
>> +
>> +2.  **Optional.** Acquire the visible resolution via
>> +    :c:func:`VIDIOC_G_SELECTION`.
>> +
>> +    * **Required fields:**
>> +
>> +      ``type``
>> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
>> +
>> +      ``target``
>> +          set to ``V4L2_SEL_TGT_COMPOSE``.
>> +
>> +    * **Return fields:**
>> +
>> +      ``r.left``, ``r.top``, ``r.width``, ``r.height``
>> +          the visible rectangle; it must fit within the frame buffer resolution
>> +          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
>> +
>> +    * The following selection targets are supported on ``CAPTURE``:
>> +
>> +      ``V4L2_SEL_TGT_CROP_BOUNDS``
>> +          corresponds to the coded resolution of the stream.
>> +
>> +      ``V4L2_SEL_TGT_CROP_DEFAULT``
>> +          the rectangle covering the part of the ``CAPTURE`` buffer that
>> +          contains meaningful picture data (visible area); width and height
>> +          will be equal to the visible resolution of the stream.
>> +
>> +      ``V4L2_SEL_TGT_CROP``
>> +          the rectangle within the coded resolution to be output to
>> +          ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
>> +          hardware without additional compose/scaling capabilities.
>> +
>> +      ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
>> +          the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
>> +          frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
>> +          hardware does not support compose/scaling.
>> +
>> +      ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
>> +          equal to ``V4L2_SEL_TGT_CROP``.
>> +
>> +      ``V4L2_SEL_TGT_COMPOSE``
>> +          the rectangle inside a ``CAPTURE`` buffer into which the cropped
>> +          frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
>> +          read-only on hardware without additional compose/scaling capabilities.
>> +
>> +      ``V4L2_SEL_TGT_COMPOSE_PADDED``
>> +          the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
>> +          hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
>> +          write padding pixels.
>> +
>> +    .. warning::
>> +
>> +       The values are guaranteed to be meaningful only after the decoder
>> +       successfully parses the stream metadata. The client must not rely on the
>> +       query before that happens.
>> +
>> +3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
>> +    the ``CAPTURE`` queue. Once the stream information is parsed and known, the
>> +    client may use this ioctl to discover which raw formats are supported for
>> +    given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
>> +
>> +    .. important::
>> +
>> +       The decoder will return only formats supported for the currently
>> +       established coded format, as per the ``OUTPUT`` format and/or stream
>> +       metadata parsed in this initialization sequence, even if more formats
>> +       may be supported by the decoder in general. In other words, the set
>> +       returned will be a subset of the initial query mentioned in the
>> +       `Querying capabilities` section.
>> +
>> +       For example, a decoder may support YUV and RGB formats for resolutions
>> +       1920x1088 and lower, but only YUV for higher resolutions (due to
>> +       hardware limitations). After parsing a resolution of 1920x1088 or lower,
>> +       :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
>> +       but after parsing resolution higher than 1920x1088, the decoder will not
>> +       return RGB, unsupported for this resolution.
>> +
>> +       However, subsequent resolution change event triggered after
>> +       discovering a resolution change within the same stream may switch
>> +       the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
>> +       would return RGB formats again in that case.
>> +
>> +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
>> +    ``CAPTURE`` queue. The client may choose a different format than
>> +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
>> +
>> +    * **Required fields:**
>> +
>> +      ``type``
>> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
>> +
>> +      ``pixelformat``
>> +          a raw pixel format.
>> +
>> +   * Setting the ``CAPTURE`` format will reset the compose selection rectangles
>> +     to their default values, based on the new resolution, as described in the
>> +     previous step.
>> +
>> +5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
>> +   the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
>> +   scaling capabilities.
>> +
>> +   * **Required fields:**
>> +
>> +     ``type``
>> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
>> +
>> +     ``target``
>> +         set to ``V4L2_SEL_TGT_COMPOSE``.
>> +
>> +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
>> +         the rectangle inside a ``CAPTURE`` buffer into which the cropped
>> +         frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
>> +         read-only on hardware without additional compose/scaling capabilities.
>> +
>> +   * **Return fields:**
>> +
>> +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
>> +         the visible rectangle; it must fit within the frame buffer resolution
>> +         returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
>> +
>> +   .. warning::
>> +
>> +      The decoder may adjust the compose rectangle to the nearest
>> +      supported one to meet codec and hardware requirements. The client needs
>> +      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
>> +
>> +6.  If all the following conditions are met, the client may resume the decoding
>> +    instantly:
>> +
>> +    * ``sizeimage`` of the new format (determined in previous steps) is less
>> +      than or equal to the size of currently allocated buffers,
>> +
>> +    * the number of buffers currently allocated is greater than or equal to the
>> +      minimum number of buffers acquired in previous steps. To fulfill this
>> +      requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
>> +      buffers.
>> +
>> +    In that case, the remaining steps do not apply and the client may resume
>> +    the decoding by one of the following actions:
>> +
>> +    * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
>> +      with the ``V4L2_DEC_CMD_START`` command,
>> +
>> +    * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
>> +      on the ``CAPTURE`` queue.
>> +
>> +    However, if the client intends to change the buffer set, to lower
>> +    memory usage or for any other reasons, it may be achieved by following
>> +    the steps below.
>> +
>> +7.  **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
>> +    buffers on the ``CAPTURE`` queue until a buffer marked with the
>> +    ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
>> +
>> +8.  **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
>> +    on the ``CAPTURE`` queue to stop streaming.
>> +
>> +    .. warning::
>> +
>> +       The ``OUTPUT`` queue must remain streaming. Calling
>> +       :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
>> +       seek.
>> +
>> +9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
>> +    buffers using :c:func:`VIDIOC_REQBUFS`.
>> +
>> +    * **Required fields:**
>> +
>> +      ``count``
>> +          set to 0.
>> +
>> +      ``type``
>> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
>> +
>> +      ``memory``
>> +          follows standard semantics.
>> +
>> +10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
>> +    ``CAPTURE`` queue.
>> +
>> +    * **Required fields:**
>> +
>> +      ``count``
>> +          requested number of buffers to allocate; greater than zero.
>> +
>> +      ``type``
>> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
>> +
>> +      ``memory``
>> +          follows standard semantics.
>> +
>> +    * **Return fields:**
>> +
>> +      ``count``
>> +          actual number of buffers allocated.
>> +
>> +    .. warning::
>> +
>> +       The actual number of allocated buffers may differ from the ``count``
>> +       given. The client must check the updated value of ``count`` after the
>> +       call returns.
>> +
>> +    .. note::
>> +
>> +       To allocate more than the minimum number of buffers (for pipeline
>> +       depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
>> +       control to get the minimum number of buffers required, and pass the
>> +       obtained value plus the number of additional buffers needed in the
>> +       ``count`` field to :c:func:`VIDIOC_REQBUFS`.
>> +
>> +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
>> +    used to have more control over buffer allocation. For example, by
>> +    allocating buffers larger than the current ``CAPTURE`` format, future
>> +    resolution changes can be accommodated.
>> +
>> +    * **Required fields:**
>> +
>> +      ``count``
>> +          requested number of buffers to allocate; greater than zero.
>> +
>> +      ``type``
>> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
>> +
>> +      ``memory``
>> +          follows standard semantics.
>> +
>> +      ``format``
>> +          a format representing the maximum framebuffer resolution to be
>> +          accommodated by newly allocated buffers.
>> +
>> +    * **Return fields:**
>> +
>> +      ``count``
>> +          adjusted to the number of allocated buffers.
>> +
>> +    .. warning::
>> +
>> +        The actual number of allocated buffers may differ from the ``count``
>> +        given. The client must check the updated value of ``count`` after the
>> +        call returns.
>> +
>> +    .. note::
>> +
>> +       To allocate buffers for a format different than parsed from the stream
>> +       metadata, the client must proceed as follows, before the metadata
>> +       parsing is initiated:
>> +
>> +       * set width and height of the ``OUTPUT`` format to desired coded resolution to
>> +         let the decoder configure the ``CAPTURE`` format appropriately,
>> +
>> +       * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
>> +         until this step.
>> +
>> +       The format obtained in the query may be then used with
>> +       :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
>> +
>> +11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
>> +    frames.
>> +
>> +Decoding
>> +========
>> +
>> +This state is reached after the `Capture setup` sequence finishes successfully.
>> +In this state, the client queues and dequeues buffers to both queues via
>> +:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
>> +semantics.
>> +
>> +The content of the source ``OUTPUT`` buffers depends on the active coded pixel
>> +format and may be affected by codec-specific extended controls, as stated in
>> +the documentation of each format.
>> +
>> +Both queues operate independently, following the standard behavior of V4L2
>> +buffer queues and memory-to-memory devices. In addition, the order of decoded
>> +frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
>> +coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
>> +format, e.g. frame reordering.
>> +
>> +The client must not assume any direct relationship between ``CAPTURE``
>> +and ``OUTPUT`` buffers and any specific timing of buffers becoming
>> +available to dequeue. Specifically:
>> +
>> +* a buffer queued to ``OUTPUT`` may result in no buffers being produced
>> +  on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
>> +  metadata syntax structures are present in it),
>> +
>> +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
>> +  on ``CAPTURE`` (if the encoded data contained more than one frame, or if
>> +  returning a decoded frame allowed the decoder to return a frame that
>> +  preceded it in decode, but succeeded it in the display order),
>> +
>> +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
>> +  ``CAPTURE`` later into decode process, and/or after processing further
>> +  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
>> +  reordering is used,
>> +
>> +* buffers may become available on the ``CAPTURE`` queue without additional
>> +  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
>> +  ``OUTPUT`` buffers queued in the past whose decoding results are only
>> +  available at later time, due to specifics of the decoding process.
>> +
>> +.. note::
>> +
>> +   To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
>> +   originated from, the client can set the ``timestamp`` field of the
>> +   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
>> +   ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
>> +   will have their ``timestamp`` field set to the same value when dequeued.
>> +
>> +   In addition to the straightforward case of one ``OUTPUT`` buffer producing
>> +   one ``CAPTURE`` buffer, the following cases are defined:
>> +
>> +   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
>> +     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
>> +
>> +   * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
>> +     the ``OUTPUT`` buffer queued last will be copied.
>> +
>> +   * the decoding order differs from the display order (i.e. the ``CAPTURE``
>> +     buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
>> +     timestamps will not retain the order of ``OUTPUT`` timestamps.
>> +
>> +During the decoding, the decoder may initiate one of the special sequences, as
>> +listed below. The sequences will result in the decoder returning all the
>> +``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
>> +before the sequence started. Last of the buffers will have the
>> +``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
>> +must check if there is any pending event and:
>> +
>> +* if a ``V4L2_EVENT_SOURCE_CHANGE`` event is pending, the `Dynamic resolution
>> +  change` sequence needs to be followed,
>> +
>> +* if a ``V4L2_EVENT_EOS`` event is pending, the `End of stream` sequence needs
>> +  to be followed.
>> +
>> +Some of the sequences can be intermixed with each other and need to be handled
>> +as they happen. The exact operation is documented for each sequence.
>> +
>> +Should a decoding error occur, it will be reported to the client with the level
>> +of details depending on the decoder capabilities. Specifically:
>> +
>> +* the CAPTURE buffer that contains the results of the failed decode operation
>> +  will be returned with the V4L2_BUF_FLAG_ERROR flag set,
>> +
>> +* if the decoder is able to precisely report the OUTPUT buffer that triggered
>> +  the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
>> +  set.
>> +
>> +In case of a fatal failure that does not allow the decoding to continue, any
>> +further operations on corresponding decoder file handle will return the -EIO
>> +error code. The client may close the file handle and open a new one, or
>> +alternatively reinitialize the instance by stopping streaming on both queues,
>> +releasing all buffers and performing the Initialization sequence again.
>> +
>> +Seek
>> +====
>> +
>> +Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
>> +The seek does not require any specific operation on the ``CAPTURE`` queue, but
>> +it may be affected as per normal decoder operation.
>> +
>> +1. Stop the ``OUTPUT`` queue to begin the seek sequence via
>> +   :c:func:`VIDIOC_STREAMOFF`.
>> +
>> +   * **Required fields:**
>> +
>> +     ``type``
>> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
>> +
>> +   * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
>> +     treated as returned to the client (following standard semantics).
>> +
>> +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`
>> +
>> +   * **Required fields:**
>> +
>> +     ``type``
>> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
>> +
>> +   * The decoder will start accepting new source bitstream buffers after the
>> +     call returns.
>> +
>> +3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
>> +   queue until a suitable resume point is found.
>> +
>> +   .. note::
>> +
>> +      There is no requirement to begin queuing coded data starting exactly
>> +      from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
>> +      buffers will be processed and returned to the client until a suitable
>> +      resume point is found.  While looking for a resume point, the decoder
>> +      should not produce any decoded frames into ``CAPTURE`` buffers.
>> +
>> +      Some hardware is known to mishandle seeks to a non-resume point. Such an
>> +      operation may result in an unspecified number of corrupted decoded frames
>> +      being made available on the ``CAPTURE`` queue. Drivers must ensure that
>> +      no fatal decoding errors or crashes occur, and implement any necessary
>> +      handling and workarounds for hardware issues related to seek operations.
>> +
>> +   .. warning::
>> +
>> +      In case of the H.264/HEVC codec, the client must take care not to seek
>> +      over a change of SPS/PPS. Even though the target frame could be a
>> +      keyframe, the stale SPS/PPS inside decoder state would lead to undefined
>> +      results when decoding. Although the decoder must handle that case without
>> +      a crash or a fatal decode error, the client must not expect a sensible
>> +      decode output.
>> +
>> +      If the hardware can detect such corrupted decoded frames, then
>> +      corresponding buffers will be returned to the client with the
>> +      V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
>> +      description of decode error reporting.
>> +
>> +4. After a resume point is found, the decoder will start returning ``CAPTURE``
>> +   buffers containing decoded frames.
>> +
>> +.. important::
>> +
>> +   A seek may result in the `Dynamic resolution change` sequence being
>> +   initiated, due to the seek target having decoding parameters different from
>> +   the part of the stream decoded before the seek. The sequence must be handled
>> +   as per normal decoder operation.
>> +
>> +.. warning::
>> +
>> +   It is not specified when the ``CAPTURE`` queue starts producing buffers
>> +   containing decoded data from the ``OUTPUT`` buffers queued after the seek,
>> +   as it operates independently from the ``OUTPUT`` queue.
>> +
>> +   The decoder may return a number of remaining ``CAPTURE`` buffers containing
>> +   decoded frames originating from the ``OUTPUT`` buffers queued before the
>> +   seek sequence is performed.
>> +
>> +   The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
>> +   ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
>> +   queued before the seek sequence may have matching ``CAPTURE`` buffers
>> +   produced.  For example, given the sequence of operations on the
>> +   ``OUTPUT`` queue:
>> +
>> +     QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
>> +
>> +   any of the following results on the ``CAPTURE`` queue is allowed:
>> +
>> +     {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}.
>> +
>> +   To determine the CAPTURE buffer containing the first decoded frame after the
>> +   seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
>> +   buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
>> +   decoder.
>> +
>> +.. note::
>> +
>> +   To achieve instantaneous seek, the client may restart streaming on the
>> +   ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
>> +
>> +Dynamic resolution change
>> +=========================
>> +
>> +Streams that include resolution metadata in the bitstream may require switching
>> +to a different resolution during the decoding.
>> +
>> +The sequence starts when the decoder detects a coded frame with one or more of
>> +the following parameters different from those previously established (and
>> +reflected by corresponding queries):
>> +
>> +* coded resolution (``OUTPUT`` width and height),
>> +
>> +* visible resolution (selection rectangles),
>> +
>> +* the minimum number of buffers needed for decoding.
>> +
>> +Whenever that happens, the decoder must proceed as follows:
>> +
>> +1.  After encountering a resolution change in the stream, the decoder sends a
>> +    ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
>> +    ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> 
> What about a format changes that does now affect the resolution, like a
> pixel format change ? Also, what about changes that don't require a

A pixel format change always implies a resolution change.

> reallocation ? Like a change in the colorimetry parameters ? I don't
> think the spec need to initially cover it all, but we need to make sure
> there is a mechanism for userspace to know at which frames to read back
> the new format (G_FMT). Maybe we need both an event and a buffer flag
> to mark it ?

After a SOURCE_CHANGE event is received, G_FMT returns the *new* format,
including colorimetry. This will become the active format once the drain
operation finished.

If that's not clear from the spec, then I need to improve it.

Regards,

	Hans

> 
>> +
>> +    .. important::
>> +
>> +       Any client query issued after the decoder queues the event will return
>> +       values applying to the stream after the resolution change, including
>> +       queue formats, selection rectangles and controls.
>> +
>> +2.  The decoder will then process and decode all remaining buffers from before
>> +    the resolution change point.
>> +
>> +    * The last buffer from before the change must be marked with the
>> +      ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
>> +
>> +    .. warning::
>> +
>> +       The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
>> +       = 0) and in that case it must be ignored by the client, as it does not
>> +       contain a decoded frame.
>> +
>> +    .. note::
>> +
>> +       Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
>> +       with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
>> +       :c:func:`VIDIOC_DQBUF`.
>> +
>> +The client must continue the sequence as described below to continue the
>> +decoding process.
>> +
>> +1.  Dequeue the source change event.
>> +
>> +    .. important::
>> +
>> +       A source change triggers an implicit decoder drain, similar to the
>> +       explicit `Drain` sequence. The decoder is stopped after it completes.
>> +       The decoding process must be resumed with either a pair of calls to
>> +       :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
>> +       ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
>> +       ``V4L2_DEC_CMD_START`` command.
>> +
>> +2.  Continue with the `Capture setup` sequence.
>> +
>> +.. note::
>> +
>> +   During the resolution change sequence, the ``OUTPUT`` queue must remain
>> +   streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
>> +   abort the sequence and initiate a seek.
>> +
>> +   In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
>> +   queue and this remains true for the duration of the entire resolution change
>> +   sequence as well.
>> +
>> +   The client should, for best performance and simplicity, keep queuing/dequeuing
>> +   buffers to/from the ``OUTPUT`` queue even while processing this sequence.
>> +
>> +Drain
>> +=====
>> +
>> +To ensure that all queued ``OUTPUT`` buffers have been processed and related
>> +``CAPTURE`` buffers are given to the client, the client must follow the drain
>> +sequence described below. After the drain sequence ends, the client has
>> +received all decoded frames for all ``OUTPUT`` buffers queued before the
>> +sequence was started.
>> +
>> +1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
>> +
>> +   * **Required fields:**
>> +
>> +     ``cmd``
>> +         set to ``V4L2_DEC_CMD_STOP``.
>> +
>> +     ``flags``
>> +         set to 0.
>> +
>> +     ``pts``
>> +         set to 0.
>> +
>> +   .. warning::
>> +
>> +      The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
>> +      queues are streaming. For compatibility reasons, the call to
>> +      :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
>> +      not streaming, but at the same time it will not initiate the `Drain`
>> +      sequence and so the steps described below would not be applicable.
>> +
>> +2. Any ``OUTPUT`` buffers queued by the client before the
>> +   :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
>> +   normal. The client must continue to handle both queues independently,
>> +   similarly to normal decode operation. This includes:
>> +
>> +   * handling any operations triggered as a result of processing those buffers,
>> +     such as the `Dynamic resolution change` sequence, before continuing with
>> +     the drain sequence,
>> +
>> +   * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
>> +     ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
>> +
>> +     .. warning::
>> +
>> +        The last buffer may be empty (with :c:type:`v4l2_buffer`
>> +        ``bytesused`` = 0) and in that case it must be ignored by the client,
>> +        as it does not contain a decoded frame.
>> +
>> +     .. note::
>> +
>> +        Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
>> +        marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
>> +        :c:func:`VIDIOC_DQBUF`.
>> +
>> +   * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
>> +     before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
>> +
>> +   * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
>> +
>> +   .. note::
>> +
>> +      For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
>> +      event when the last frame has been decoded and all frames are ready to be
>> +      dequeued. It is a deprecated behavior and the client must not rely on it.
>> +      The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
>> +
>> +3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
>> +   are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
>> +   stopped and it will accept, but not process, any newly queued ``OUTPUT``
>> +   buffers until the client issues any of the following operations:
>> +
>> +   * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
>> +     operation normally, with all the state from before the drain,
>> +
>> +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
>> +     ``CAPTURE`` queue - the decoder will resume the operation normally,
>> +     however any ``CAPTURE`` buffers still in the queue will be returned to the
>> +     client,
>> +
>> +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
>> +     ``OUTPUT`` queue - any pending source buffers will be returned to the
>> +     client and the `Seek` sequence will be triggered.
>> +
>> +.. note::
>> +
>> +   Once the drain sequence is initiated, the client needs to drive it to
>> +   completion, as described by the steps above, unless it aborts the process by
>> +   issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
>> +   queues.  The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
>> +   ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
>> +   will fail with -EBUSY error code if attempted.
>> +
>> +   Although mandatory, the availability of decoder commands may be queried
>> +   using :c:func:`VIDIOC_TRY_DECODER_CMD`.
>> +
>> +End of stream
>> +=============
>> +
>> +If the decoder encounters an end of stream marking in the stream, the decoder
>> +will initiate the `Drain` sequence, which the client must handle as described
>> +above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
>> +
>> +Commit points
>> +=============
>> +
>> +Setting formats and allocating buffers trigger changes in the behavior of the
>> +decoder.
>> +
>> +1. Setting the format on the ``OUTPUT`` queue may change the set of formats
>> +   supported/advertised on the ``CAPTURE`` queue. In particular, it also means
>> +   that the ``CAPTURE`` format may be reset and the client must not rely on the
>> +   previously set format being preserved.
>> +
>> +2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
>> +   supported for the current ``OUTPUT`` format.
>> +
>> +3. Setting the format on the ``CAPTURE`` queue does not change the list of
>> +   formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
>> +   format that is not supported for the currently selected ``OUTPUT`` format
>> +   will result in the decoder adjusting the requested ``CAPTURE`` format to a
>> +   supported one.
>> +
>> +4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
>> +   supported coded formats, irrespectively of the current ``CAPTURE`` format.
>> +
>> +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
>> +   the client must not change the format on the ``OUTPUT`` queue. Drivers will
>> +   return the -EBUSY error code for any such format change attempt.
>> +
>> +To summarize, setting formats and allocation must always start with the
>> +``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
>> +set of supported formats for the ``CAPTURE`` queue.
>> diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
>> index 67a980818dc8..caa05f5f6380 100644
>> --- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
>> +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
>> @@ -39,4 +39,10 @@ file handle is visible through another file handle).
>>  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
>> diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
>> index 71eebfc6d853..caf14e440447 100644
>> --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
>> +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
>> @@ -39,6 +39,11 @@ Single-planar format structure
>>  	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.
>> diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
>> index 004ec00db6bd..97015b9b40b8 100644
>> --- a/Documentation/media/uapi/v4l/v4l2.rst
>> +++ b/Documentation/media/uapi/v4l/v4l2.rst
>> @@ -60,6 +60,10 @@ Authors, in alphabetical order:
>>  
>>    - 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.
>> @@ -68,6 +72,10 @@ Authors, in alphabetical order:
>>  
>>    - 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.
>> @@ -92,7 +100,7 @@ Authors, in alphabetical order:
>>  
>>    - 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.
>> diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
>> index ccf83b05afa7..57f0066f4cff 100644
>> --- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
>> +++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
>> @@ -56,14 +56,16 @@ The ``cmd`` field must contain the command code. Some commands use the
>>  
>>  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}|
>> @@ -167,26 +169,32 @@ introduced in Linux 3.3.
>>  	``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
>> @@ -209,6 +217,11 @@ 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.
>>  
>> +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.
>>  

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Nicolas Dufresne]

Le mardi 11 juin 2019 à 10:29 +0200, Hans Verkuil a écrit :
> On 6/10/19 9:54 PM, Nicolas Dufresne wrote:
> > Hi Hans,
> > 
> > I went through it, and I think we are close to ready. Unfortunately, I
> > believe the SOURCE_CHANGE event is still under specified. There was a
> > post recently to try and add a new flag for changes in color space
> > which is not included here. We are also missing a workflow for changes
> > that don't affect the allocation but will affect the rendering on a
> > display (like colorimetry). Userspace needs to know at which frames
> > these parameter changes in order to signal that to the following
> > processing block. I think we must have a plane for this.
> 
> Yes, we need a new flag for the SOURCE_CHANGE event to indicate colorimetry
> changes. That's actually useful for e.g. HDMI receivers as well.
> 
> But I don't see why that should make much of a change to the spec: you still
> have to drain the capture queue, the only difference is that you don't need
> to reallocate buffers, you can just restart the decoder.

I don't think you need to drain the queue if the change is just
metadata that have no impact on the buffers allocation or layout. I
think we should have a way to communicate these changed while
streaming. Basically, something like the event, but serialized.

> 
> My intention was to get this spec in first, then extend it once we have a new
> colorimetry change flag.
> 
> > Another aspect, I'd like if we could relax a bit the bits about dynamic
> > resolutions, making some space for the "static resolution" cases.
> > Something to keep in mind, these "static resolution" HW might not be
> > able to inform userspace of the display size of the picture, we should
> > check with Maxime what happens with the Amlogic.
> 
> I've asked him about that in another email thread:
> 
> https://www.mail-archive.com/linux-media@vger.kernel.org/msg147652.html
> 
> Maxime, related to that: can the amlogic detect midstream colorimetry
> changes? Or is that also impossible?
> 
> > Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> > > From: Tomasz Figa <tfiga@chromium.org>
> > > 
> > > Due to complexity of the video decoding process, the V4L2 drivers of
> > > stateful decoder hardware require specific sequences of V4L2 API calls
> > > to be followed. These include capability enumeration, initialization,
> > > decoding, seek, pause, dynamic resolution change, drain and end of
> > > stream.
> > > 
> > > Specifics of the above have been discussed during Media Workshops at
> > > LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
> > > Conference Europe 2014 in Düsseldorf. The de facto Codec API that
> > > originated at those events was later implemented by the drivers we already
> > > have merged in mainline, such as s5p-mfc or coda.
> > > 
> > > The only thing missing was the real specification included as a part of
> > > Linux Media documentation. Fix it now and document the decoder part of
> > > the Codec API.
> > > 
> > > Signed-off-by: Tomasz Figa <tfiga@chromium.org>
> > > Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> > > ---
> > >  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
> > >  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
> > >  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
> > >  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
> > >  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
> > >  5 files changed, 1132 insertions(+), 16 deletions(-)
> > >  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> > > 
> > > diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst
> > > new file mode 100644
> > > index 000000000000..b106f2d97c48
> > > --- /dev/null
> > > +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
> > > @@ -0,0 +1,1084 @@
> > > +.. SPDX-License-Identifier: GPL-2.0
> > > +
> > > +.. _decoder:
> > > +
> > > +*************************************************
> > > +Memory-to-memory Stateful Video Decoder Interface
> > > +*************************************************
> > > +
> > > +A stateful video decoder takes complete chunks of the bitstream (e.g. Annex-B
> > > +H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
> > 
> > (minor, may ignore)
> > This isn't very precise, do we expect to document this per-format ? I
> > think we should maybe say "a complete frame of the bitstream", that
> > being said, I think stateful CODEC should be allowed to implement the
> > per-slice/per-frame control we are adding to stateless CODEC. Maybe
> > something like "documented complete chunks of bitstream" ?
> > 
> > > +display order. The decoder is expected not to require any additional information
> > > +from the client to process these buffers.
> > > +
> > > +Performing software parsing, processing etc. of the stream in the driver in
> > > +order to support this interface is strongly discouraged. In case such
> > > +operations are needed, use of the Stateless Video Decoder Interface (in
> > > +development) is strongly advised.
> > > +
> > > +Conventions and notation used in this document
> > > +==============================================
> > > +
> > > +1. The general V4L2 API rules apply if not specified in this document
> > > +   otherwise.
> > > +
> > > +2. The meaning of words "must", "may", "should", etc. is as per `RFC
> > > +   2119 <https://tools.ietf.org/html/rfc2119>`_.
> > > +
> > > +3. All steps not marked "optional" are required.
> > > +
> > > +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
> > > +   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
> > > +   unless specified otherwise.
> > > +
> > > +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
> > > +   used interchangeably with multi-planar API, unless specified otherwise,
> > > +   depending on decoder capabilities and following the general V4L2 guidelines.
> > > +
> > > +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
> > > +   [0..2]: i = 0, 1, 2.
> > > +
> > > +7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
> > > +   queue containing data that resulted from processing buffer A.
> > > +
> > > +.. _decoder-glossary:
> > > +
> > > +Glossary
> > > +========
> > > +
> > > +CAPTURE
> > > +   the destination buffer queue; for decoders, the queue of buffers containing
> > > +   decoded frames; for encoders, the queue of buffers containing an encoded
> > > +   bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
> > > +   ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
> > > +   into ``CAPTURE`` buffers.
> > > +
> > > +client
> > > +   the application communicating with the decoder or encoder implementing
> > > +   this interface.
> > > +
> > > +coded format
> > > +   encoded/compressed video bitstream format (e.g. H.264, VP8, etc.); see
> > > +   also: raw format.
> > > +
> > > +coded height
> > > +   height for given coded resolution.
> > > +
> > > +coded resolution
> > > +   stream resolution in pixels aligned to codec and hardware requirements;
> > > +   typically visible resolution rounded up to full macroblocks;
> > > +   see also: visible resolution.
> > > +
> > > +coded width
> > > +   width for given coded resolution.
> > > +
> > > +decode order
> > > +   the order in which frames are decoded; may differ from display order if the
> > > +   coded format includes a feature of frame reordering; for decoders,
> > > +   ``OUTPUT`` buffers must be queued by the client in decode order; for
> > > +   encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
> > > +
> > > +destination
> > > +   data resulting from the decode process; see ``CAPTURE``.
> > > +
> > > +display order
> > > +   the order in which frames must be displayed; for encoders, ``OUTPUT``
> > > +   buffers must be queued by the client in display order; for decoders,
> > > +   ``CAPTURE`` buffers must be returned by the decoder in display order.
> > > +
> > > +DPB
> > > +   Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
> > > +   raw frame available for reference in further decoding steps.
> > > +
> > > +EOS
> > > +   end of stream.
> > > +
> > > +IDR
> > > +   Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
> > > +   stream, which clears the list of earlier reference frames (DPBs).
> > > +
> > > +keyframe
> > > +   an encoded frame that does not reference frames decoded earlier, i.e.
> > > +   can be decoded fully on its own.
> > > +
> > > +macroblock
> > > +   a processing unit in image and video compression formats based on linear
> > > +   block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
> > > +   popular codecs the size is 16x16 samples (pixels).
> > > +
> > > +OUTPUT
> > > +   the source buffer queue; for decoders, the queue of buffers containing
> > > +   an encoded bitstream; for encoders, the queue of buffers containing raw
> > > +   frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
> > > +   ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
> > > +   from ``OUTPUT`` buffers.
> > > +
> > > +PPS
> > > +   Picture Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> > > +
> > > +raw format
> > > +   uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
> > > +
> > > +resume point
> > > +   a point in the bitstream from which decoding may start/continue, without
> > > +   any previous state/data present, e.g.: a keyframe (VP8/VP9) or
> > > +   SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
> > > +   of a new stream, or to resume decoding after a seek.
> > > +
> > > +source
> > > +   data fed to the decoder or encoder; see ``OUTPUT``.
> > > +
> > > +source height
> > > +   height in pixels for given source resolution; relevant to encoders only.
> > > +
> > > +source resolution
> > > +   resolution in pixels of source frames being source to the encoder and
> > > +   subject to further cropping to the bounds of visible resolution; relevant to
> > > +   encoders only.
> > > +
> > > +source width
> > > +   width in pixels for given source resolution; relevant to encoders only.
> > > +
> > > +SPS
> > > +   Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> > > +
> > > +stream metadata
> > > +   additional (non-visual) information contained inside encoded bitstream;
> > > +   for example: coded resolution, visible resolution, codec profile.
> > > +
> > > +visible height
> > > +   height for given visible resolution; display height.
> > > +
> > > +visible resolution
> > > +   stream resolution of the visible picture, in pixels, to be used for
> > > +   display purposes; must be smaller or equal to coded resolution;
> > > +   display resolution.
> > > +
> > > +visible width
> > > +   width for given visible resolution; display width.
> > > +
> > > +State machine
> > > +=============
> > > +
> > > +.. kernel-render:: DOT
> > > +   :alt: DOT digraph of decoder state machine
> > > +   :caption: Decoder state machine
> > > +
> > > +   digraph decoder_state_machine {
> > > +       node [shape = doublecircle, label="Decoding"] Decoding;
> > > +
> > > +       node [shape = circle, label="Initialization"] Initialization;
> > > +       node [shape = circle, label="Capture\nsetup"] CaptureSetup;
> > > +       node [shape = circle, label="Dynamic\nresolution\nchange"] ResChange;
> > > +       node [shape = circle, label="Stopped"] Stopped;
> > > +       node [shape = circle, label="Drain"] Drain;
> > > +       node [shape = circle, label="Seek"] Seek;
> > > +       node [shape = circle, label="End of stream"] EoS;
> > > +
> > > +       node [shape = point]; qi
> > > +       qi -> Initialization [ label = "open()" ];
> > > +
> > > +       Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> > > +
> > > +       CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
> > > +
> > > +       Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
> > > +       Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
> > > +       Decoding -> EoS [ label = "EoS mark\nin the stream" ];
> > > +       Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > +       Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
> > > +       Decoding -> Decoding;
> > > +
> > > +       ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> > > +       ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > +
> > > +       EoS -> Drain [ label = "Implicit\ndrain" ];
> > > +
> > > +       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
> > > +       Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > +
> > > +       Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
> > > +       Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
> > > +
> > > +       Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
> > > +       Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > +   }
> > > +
> > > +Querying capabilities
> > > +=====================
> > > +
> > > +1. To enumerate the set of coded formats supported by the decoder, the
> > > +   client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
> > > +
> > > +   * The full set of supported formats will be returned, regardless of the
> > > +     format set on ``CAPTURE``.
> > > +
> > > +2. To enumerate the set of supported raw formats, the client may call
> > > +   :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
> > > +
> > > +   * Only the formats supported for the format currently active on ``OUTPUT``
> > > +     will be returned.
> > > +
> > > +   * In order to enumerate raw formats supported by a given coded format,
> > > +     the client must first set that coded format on ``OUTPUT`` and then
> > > +     enumerate formats on ``CAPTURE``.
> > > +
> > > +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
> > > +   resolutions for a given format, passing desired pixel format in
> > > +   :c:type:`v4l2_frmsizeenum` ``pixel_format``.
> > > +
> > > +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
> > > +     format will include all possible coded resolutions supported by the
> > > +     decoder for given coded pixel format.
> > > +
> > > +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
> > > +     will include all possible frame buffer resolutions supported by the
> > > +     decoder for given raw pixel format and the coded format currently set on
> > > +     ``OUTPUT``.
> > > +
> > > +4. Supported profiles and levels for the coded format currently set on
> > > +   ``OUTPUT``, if applicable, may be queried using their respective controls
> > > +   via :c:func:`VIDIOC_QUERYCTRL`.
> > > +
> > > +Initialization
> > > +==============
> > > +
> > > +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
> > > +
> > > +   * **Required fields:**
> > > +
> > > +     ``type``
> > > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > +
> > > +     ``pixelformat``
> > > +         a coded pixel format.
> > > +
> > > +     ``width``, ``height``
> > > +         coded resolution of the stream; required only if it cannot be parsed
> > > +         from the stream for the given coded format; otherwise the decoder will
> > > +         use this resolution as a placeholder resolution that will likely change
> > > +         as soon as it can parse the actual coded resolution from the stream.
> > > +
> > > +     ``sizeimage``
> > > +         desired size of ``OUTPUT`` buffers; the decoder may adjust it to
> > > +         match hardware requirements.
> > > +
> > > +     other fields
> > > +         follow standard semantics.
> > > +
> > > +   * **Return fields:**
> > > +
> > > +     ``sizeimage``
> > > +         adjusted size of ``OUTPUT`` buffers.
> > > +
> > > +   * The ``CAPTURE`` format will be updated with an appropriate frame buffer
> > > +     resolution instantly based on the width and height returned by
> > > +     :c:func:`VIDIOC_S_FMT`.
> > > +     However, for coded formats that include stream resolution information,
> > > +     after the decoder is done parsing the information from the stream, it will
> > > +     update the ``CAPTURE`` format with new values and signal a source change
> > > +     event, regardless of whether they match the values set by the client or
> > > +     not.
> > > +
> > > +   .. important::
> > > +
> > > +      Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
> > > +      format. How the new ``CAPTURE`` format is determined is up to the decoder
> > > +      and the client must ensure it matches its needs afterwards.
> > > +
> > > +2.  Allocate source (bitstream) buffers via :c:func:`VIDIOC_REQBUFS` on
> > > +    ``OUTPUT``.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``count``
> > > +          requested number of buffers to allocate; greater than zero.
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > +
> > > +      ``memory``
> > > +          follows standard semantics.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``count``
> > > +          the actual number of buffers allocated.
> > > +
> > > +    .. warning::
> > > +
> > > +       The actual number of allocated buffers may differ from the ``count``
> > > +       given. The client must check the updated value of ``count`` after the
> > > +       call returns.
> > > +
> > > +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
> > > +    used to have more control over buffer allocation.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``count``
> > > +          requested number of buffers to allocate; greater than zero.
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > +
> > > +      ``memory``
> > > +          follows standard semantics.
> > > +
> > > +      ``format``
> > > +          follows standard semantics.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``count``
> > > +          adjusted to the number of allocated buffers.
> > > +
> > > +    .. warning::
> > > +
> > > +       The actual number of allocated buffers may differ from the ``count``
> > > +       given. The client must check the updated value of ``count`` after the
> > > +       call returns.
> > > +
> > > +3.  Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
> > > +
> > > +4.  **This step only applies to coded formats that contain resolution information
> > > +    in the stream.** Continue queuing/dequeuing bitstream buffers to/from the
> > > +    ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
> > > +    buffers will be processed and returned to the client in order, until
> > > +    required metadata to configure the ``CAPTURE`` queue are found. This is
> > > +    indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
> > > +    ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> > > +
> > > +    * It is not an error if the first buffer does not contain enough data for
> > > +      this to occur. Processing of the buffers will continue as long as more
> > > +      data is needed.
> > > +
> > > +    * If data in a buffer that triggers the event is required to decode the
> > > +      first frame, it will not be returned to the client, until the
> > > +      initialization sequence completes and the frame is decoded.
> > > +
> > > +    * If the client has not set the coded resolution of the stream on its own,
> > > +      calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
> > > +      :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
> > > +      queue will not return the real values for the stream until a
> > > +      ``V4L2_EVENT_SOURCE_CHANGE`` event is signaled.
> > > +
> > > +    .. important::
> > > +
> > > +       Any client query issued after the decoder queues the event will return
> > > +       values applying to the just parsed stream, including queue formats,
> > > +       selection rectangles and controls.
> > > +
> > > +    .. note::
> > > +
> > > +       A client capable of acquiring stream parameters from the bitstream on
> > > +       its own may attempt to set the width and height of the ``OUTPUT`` format
> > > +       to non-zero values matching the coded size of the stream, skip this step
> > > +       and continue with the `Capture setup` sequence. However, it must not
> > > +       rely on any driver queries regarding stream parameters, such as
> > > +       selection rectangles and controls, since the decoder has not parsed them
> > > +       from the stream yet. If the values configured by the client do not match
> > > +       those parsed by the decoder, a `Dynamic resolution change` will be
> > > +       triggered to reconfigure them.
> > > +
> > > +    .. note::
> > > +
> > > +       No decoded frames are produced during this phase.
> > > +
> > > +5.  Continue with the `Capture setup` sequence.
> > > +
> > > +Capture setup
> > > +=============
> > > +
> > > +1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
> > > +    destination buffers parsed/decoded from the bitstream.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``width``, ``height``
> > > +          frame buffer resolution for the decoded frames.
> > > +
> > > +      ``pixelformat``
> > > +          pixel format for decoded frames.
> > > +
> > > +      ``num_planes`` (for _MPLANE ``type`` only)
> > > +          number of planes for pixelformat.
> > > +
> > > +      ``sizeimage``, ``bytesperline``
> > > +          as per standard semantics; matching frame buffer format.
> > > +
> > > +    .. note::
> > > +
> > > +       The value of ``pixelformat`` may be any pixel format supported by the
> > > +       decoder for the current stream. The decoder should choose a
> > > +       preferred/optimal format for the default configuration. For example, a
> > > +       YUV format may be preferred over an RGB format if an additional
> > > +       conversion step would be required for the latter.
> > > +
> > > +2.  **Optional.** Acquire the visible resolution via
> > > +    :c:func:`VIDIOC_G_SELECTION`.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +      ``target``
> > > +          set to ``V4L2_SEL_TGT_COMPOSE``.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > > +          the visible rectangle; it must fit within the frame buffer resolution
> > > +          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> > > +
> > > +    * The following selection targets are supported on ``CAPTURE``:
> > > +
> > > +      ``V4L2_SEL_TGT_CROP_BOUNDS``
> > > +          corresponds to the coded resolution of the stream.
> > > +
> > > +      ``V4L2_SEL_TGT_CROP_DEFAULT``
> > > +          the rectangle covering the part of the ``CAPTURE`` buffer that
> > > +          contains meaningful picture data (visible area); width and height
> > > +          will be equal to the visible resolution of the stream.
> > > +
> > > +      ``V4L2_SEL_TGT_CROP``
> > > +          the rectangle within the coded resolution to be output to
> > > +          ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
> > > +          hardware without additional compose/scaling capabilities.
> > > +
> > > +      ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
> > > +          the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
> > > +          frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
> > > +          hardware does not support compose/scaling.
> > > +
> > > +      ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
> > > +          equal to ``V4L2_SEL_TGT_CROP``.
> > > +
> > > +      ``V4L2_SEL_TGT_COMPOSE``
> > > +          the rectangle inside a ``CAPTURE`` buffer into which the cropped
> > > +          frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> > > +          read-only on hardware without additional compose/scaling capabilities.
> > > +
> > > +      ``V4L2_SEL_TGT_COMPOSE_PADDED``
> > > +          the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
> > > +          hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
> > > +          write padding pixels.
> > > +
> > > +    .. warning::
> > > +
> > > +       The values are guaranteed to be meaningful only after the decoder
> > > +       successfully parses the stream metadata. The client must not rely on the
> > > +       query before that happens.
> > > +
> > > +3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
> > > +    the ``CAPTURE`` queue. Once the stream information is parsed and known, the
> > > +    client may use this ioctl to discover which raw formats are supported for
> > > +    given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
> > > +
> > > +    .. important::
> > > +
> > > +       The decoder will return only formats supported for the currently
> > > +       established coded format, as per the ``OUTPUT`` format and/or stream
> > > +       metadata parsed in this initialization sequence, even if more formats
> > > +       may be supported by the decoder in general. In other words, the set
> > > +       returned will be a subset of the initial query mentioned in the
> > > +       `Querying capabilities` section.
> > > +
> > > +       For example, a decoder may support YUV and RGB formats for resolutions
> > > +       1920x1088 and lower, but only YUV for higher resolutions (due to
> > > +       hardware limitations). After parsing a resolution of 1920x1088 or lower,
> > > +       :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
> > > +       but after parsing resolution higher than 1920x1088, the decoder will not
> > > +       return RGB, unsupported for this resolution.
> > > +
> > > +       However, subsequent resolution change event triggered after
> > > +       discovering a resolution change within the same stream may switch
> > > +       the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
> > > +       would return RGB formats again in that case.
> > > +
> > > +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
> > > +    ``CAPTURE`` queue. The client may choose a different format than
> > > +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +      ``pixelformat``
> > > +          a raw pixel format.
> > > +
> > > +   * Setting the ``CAPTURE`` format will reset the compose selection rectangles
> > > +     to their default values, based on the new resolution, as described in the
> > > +     previous step.
> > > +
> > > +5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
> > > +   the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
> > > +   scaling capabilities.
> > > +
> > > +   * **Required fields:**
> > > +
> > > +     ``type``
> > > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +     ``target``
> > > +         set to ``V4L2_SEL_TGT_COMPOSE``.
> > > +
> > > +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > > +         the rectangle inside a ``CAPTURE`` buffer into which the cropped
> > > +         frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> > > +         read-only on hardware without additional compose/scaling capabilities.
> > > +
> > > +   * **Return fields:**
> > > +
> > > +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > > +         the visible rectangle; it must fit within the frame buffer resolution
> > > +         returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> > > +
> > > +   .. warning::
> > > +
> > > +      The decoder may adjust the compose rectangle to the nearest
> > > +      supported one to meet codec and hardware requirements. The client needs
> > > +      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
> > > +
> > > +6.  If all the following conditions are met, the client may resume the decoding
> > > +    instantly:
> > > +
> > > +    * ``sizeimage`` of the new format (determined in previous steps) is less
> > > +      than or equal to the size of currently allocated buffers,
> > > +
> > > +    * the number of buffers currently allocated is greater than or equal to the
> > > +      minimum number of buffers acquired in previous steps. To fulfill this
> > > +      requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
> > > +      buffers.
> > > +
> > > +    In that case, the remaining steps do not apply and the client may resume
> > > +    the decoding by one of the following actions:
> > > +
> > > +    * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
> > > +      with the ``V4L2_DEC_CMD_START`` command,
> > > +
> > > +    * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
> > > +      on the ``CAPTURE`` queue.
> > > +
> > > +    However, if the client intends to change the buffer set, to lower
> > > +    memory usage or for any other reasons, it may be achieved by following
> > > +    the steps below.
> > > +
> > > +7.  **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
> > > +    buffers on the ``CAPTURE`` queue until a buffer marked with the
> > > +    ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
> > > +
> > > +8.  **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
> > > +    on the ``CAPTURE`` queue to stop streaming.
> > > +
> > > +    .. warning::
> > > +
> > > +       The ``OUTPUT`` queue must remain streaming. Calling
> > > +       :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
> > > +       seek.
> > > +
> > > +9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
> > > +    buffers using :c:func:`VIDIOC_REQBUFS`.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``count``
> > > +          set to 0.
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +      ``memory``
> > > +          follows standard semantics.
> > > +
> > > +10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
> > > +    ``CAPTURE`` queue.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``count``
> > > +          requested number of buffers to allocate; greater than zero.
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +      ``memory``
> > > +          follows standard semantics.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``count``
> > > +          actual number of buffers allocated.
> > > +
> > > +    .. warning::
> > > +
> > > +       The actual number of allocated buffers may differ from the ``count``
> > > +       given. The client must check the updated value of ``count`` after the
> > > +       call returns.
> > > +
> > > +    .. note::
> > > +
> > > +       To allocate more than the minimum number of buffers (for pipeline
> > > +       depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
> > > +       control to get the minimum number of buffers required, and pass the
> > > +       obtained value plus the number of additional buffers needed in the
> > > +       ``count`` field to :c:func:`VIDIOC_REQBUFS`.
> > > +
> > > +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
> > > +    used to have more control over buffer allocation. For example, by
> > > +    allocating buffers larger than the current ``CAPTURE`` format, future
> > > +    resolution changes can be accommodated.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``count``
> > > +          requested number of buffers to allocate; greater than zero.
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +      ``memory``
> > > +          follows standard semantics.
> > > +
> > > +      ``format``
> > > +          a format representing the maximum framebuffer resolution to be
> > > +          accommodated by newly allocated buffers.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``count``
> > > +          adjusted to the number of allocated buffers.
> > > +
> > > +    .. warning::
> > > +
> > > +        The actual number of allocated buffers may differ from the ``count``
> > > +        given. The client must check the updated value of ``count`` after the
> > > +        call returns.
> > > +
> > > +    .. note::
> > > +
> > > +       To allocate buffers for a format different than parsed from the stream
> > > +       metadata, the client must proceed as follows, before the metadata
> > > +       parsing is initiated:
> > > +
> > > +       * set width and height of the ``OUTPUT`` format to desired coded resolution to
> > > +         let the decoder configure the ``CAPTURE`` format appropriately,
> > > +
> > > +       * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
> > > +         until this step.
> > > +
> > > +       The format obtained in the query may be then used with
> > > +       :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
> > > +
> > > +11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
> > > +    frames.
> > > +
> > > +Decoding
> > > +========
> > > +
> > > +This state is reached after the `Capture setup` sequence finishes successfully.
> > > +In this state, the client queues and dequeues buffers to both queues via
> > > +:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
> > > +semantics.
> > > +
> > > +The content of the source ``OUTPUT`` buffers depends on the active coded pixel
> > > +format and may be affected by codec-specific extended controls, as stated in
> > > +the documentation of each format.
> > > +
> > > +Both queues operate independently, following the standard behavior of V4L2
> > > +buffer queues and memory-to-memory devices. In addition, the order of decoded
> > > +frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
> > > +coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
> > > +format, e.g. frame reordering.
> > > +
> > > +The client must not assume any direct relationship between ``CAPTURE``
> > > +and ``OUTPUT`` buffers and any specific timing of buffers becoming
> > > +available to dequeue. Specifically:
> > > +
> > > +* a buffer queued to ``OUTPUT`` may result in no buffers being produced
> > > +  on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
> > > +  metadata syntax structures are present in it),
> > > +
> > > +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
> > > +  on ``CAPTURE`` (if the encoded data contained more than one frame, or if
> > > +  returning a decoded frame allowed the decoder to return a frame that
> > > +  preceded it in decode, but succeeded it in the display order),
> > > +
> > > +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
> > > +  ``CAPTURE`` later into decode process, and/or after processing further
> > > +  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
> > > +  reordering is used,
> > > +
> > > +* buffers may become available on the ``CAPTURE`` queue without additional
> > > +  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
> > > +  ``OUTPUT`` buffers queued in the past whose decoding results are only
> > > +  available at later time, due to specifics of the decoding process.
> > > +
> > > +.. note::
> > > +
> > > +   To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
> > > +   originated from, the client can set the ``timestamp`` field of the
> > > +   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
> > > +   ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
> > > +   will have their ``timestamp`` field set to the same value when dequeued.
> > > +
> > > +   In addition to the straightforward case of one ``OUTPUT`` buffer producing
> > > +   one ``CAPTURE`` buffer, the following cases are defined:
> > > +
> > > +   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
> > > +     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
> > > +
> > > +   * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
> > > +     the ``OUTPUT`` buffer queued last will be copied.
> > > +
> > > +   * the decoding order differs from the display order (i.e. the ``CAPTURE``
> > > +     buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
> > > +     timestamps will not retain the order of ``OUTPUT`` timestamps.
> > > +
> > > +During the decoding, the decoder may initiate one of the special sequences, as
> > > +listed below. The sequences will result in the decoder returning all the
> > > +``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
> > > +before the sequence started. Last of the buffers will have the
> > > +``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
> > > +must check if there is any pending event and:
> > > +
> > > +* if a ``V4L2_EVENT_SOURCE_CHANGE`` event is pending, the `Dynamic resolution
> > > +  change` sequence needs to be followed,
> > > +
> > > +* if a ``V4L2_EVENT_EOS`` event is pending, the `End of stream` sequence needs
> > > +  to be followed.
> > > +
> > > +Some of the sequences can be intermixed with each other and need to be handled
> > > +as they happen. The exact operation is documented for each sequence.
> > > +
> > > +Should a decoding error occur, it will be reported to the client with the level
> > > +of details depending on the decoder capabilities. Specifically:
> > > +
> > > +* the CAPTURE buffer that contains the results of the failed decode operation
> > > +  will be returned with the V4L2_BUF_FLAG_ERROR flag set,
> > > +
> > > +* if the decoder is able to precisely report the OUTPUT buffer that triggered
> > > +  the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
> > > +  set.
> > > +
> > > +In case of a fatal failure that does not allow the decoding to continue, any
> > > +further operations on corresponding decoder file handle will return the -EIO
> > > +error code. The client may close the file handle and open a new one, or
> > > +alternatively reinitialize the instance by stopping streaming on both queues,
> > > +releasing all buffers and performing the Initialization sequence again.
> > > +
> > > +Seek
> > > +====
> > > +
> > > +Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
> > > +The seek does not require any specific operation on the ``CAPTURE`` queue, but
> > > +it may be affected as per normal decoder operation.
> > > +
> > > +1. Stop the ``OUTPUT`` queue to begin the seek sequence via
> > > +   :c:func:`VIDIOC_STREAMOFF`.
> > > +
> > > +   * **Required fields:**
> > > +
> > > +     ``type``
> > > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > +
> > > +   * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
> > > +     treated as returned to the client (following standard semantics).
> > > +
> > > +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`
> > > +
> > > +   * **Required fields:**
> > > +
> > > +     ``type``
> > > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > +
> > > +   * The decoder will start accepting new source bitstream buffers after the
> > > +     call returns.
> > > +
> > > +3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
> > > +   queue until a suitable resume point is found.
> > > +
> > > +   .. note::
> > > +
> > > +      There is no requirement to begin queuing coded data starting exactly
> > > +      from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
> > > +      buffers will be processed and returned to the client until a suitable
> > > +      resume point is found.  While looking for a resume point, the decoder
> > > +      should not produce any decoded frames into ``CAPTURE`` buffers.
> > > +
> > > +      Some hardware is known to mishandle seeks to a non-resume point. Such an
> > > +      operation may result in an unspecified number of corrupted decoded frames
> > > +      being made available on the ``CAPTURE`` queue. Drivers must ensure that
> > > +      no fatal decoding errors or crashes occur, and implement any necessary
> > > +      handling and workarounds for hardware issues related to seek operations.
> > > +
> > > +   .. warning::
> > > +
> > > +      In case of the H.264/HEVC codec, the client must take care not to seek
> > > +      over a change of SPS/PPS. Even though the target frame could be a
> > > +      keyframe, the stale SPS/PPS inside decoder state would lead to undefined
> > > +      results when decoding. Although the decoder must handle that case without
> > > +      a crash or a fatal decode error, the client must not expect a sensible
> > > +      decode output.
> > > +
> > > +      If the hardware can detect such corrupted decoded frames, then
> > > +      corresponding buffers will be returned to the client with the
> > > +      V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
> > > +      description of decode error reporting.
> > > +
> > > +4. After a resume point is found, the decoder will start returning ``CAPTURE``
> > > +   buffers containing decoded frames.
> > > +
> > > +.. important::
> > > +
> > > +   A seek may result in the `Dynamic resolution change` sequence being
> > > +   initiated, due to the seek target having decoding parameters different from
> > > +   the part of the stream decoded before the seek. The sequence must be handled
> > > +   as per normal decoder operation.
> > > +
> > > +.. warning::
> > > +
> > > +   It is not specified when the ``CAPTURE`` queue starts producing buffers
> > > +   containing decoded data from the ``OUTPUT`` buffers queued after the seek,
> > > +   as it operates independently from the ``OUTPUT`` queue.
> > > +
> > > +   The decoder may return a number of remaining ``CAPTURE`` buffers containing
> > > +   decoded frames originating from the ``OUTPUT`` buffers queued before the
> > > +   seek sequence is performed.
> > > +
> > > +   The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
> > > +   ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
> > > +   queued before the seek sequence may have matching ``CAPTURE`` buffers
> > > +   produced.  For example, given the sequence of operations on the
> > > +   ``OUTPUT`` queue:
> > > +
> > > +     QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
> > > +
> > > +   any of the following results on the ``CAPTURE`` queue is allowed:
> > > +
> > > +     {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}.
> > > +
> > > +   To determine the CAPTURE buffer containing the first decoded frame after the
> > > +   seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
> > > +   buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
> > > +   decoder.
> > > +
> > > +.. note::
> > > +
> > > +   To achieve instantaneous seek, the client may restart streaming on the
> > > +   ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
> > > +
> > > +Dynamic resolution change
> > > +=========================
> > > +
> > > +Streams that include resolution metadata in the bitstream may require switching
> > > +to a different resolution during the decoding.
> > > +
> > > +The sequence starts when the decoder detects a coded frame with one or more of
> > > +the following parameters different from those previously established (and
> > > +reflected by corresponding queries):
> > > +
> > > +* coded resolution (``OUTPUT`` width and height),
> > > +
> > > +* visible resolution (selection rectangles),
> > > +
> > > +* the minimum number of buffers needed for decoding.
> > > +
> > > +Whenever that happens, the decoder must proceed as follows:
> > > +
> > > +1.  After encountering a resolution change in the stream, the decoder sends a
> > > +    ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
> > > +    ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> > 
> > What about a format changes that does now affect the resolution, like a
> > pixel format change ? Also, what about changes that don't require a
> 
> A pixel format change always implies a resolution change.
> 
> > reallocation ? Like a change in the colorimetry parameters ? I don't
> > think the spec need to initially cover it all, but we need to make sure
> > there is a mechanism for userspace to know at which frames to read back
> > the new format (G_FMT). Maybe we need both an event and a buffer flag
> > to mark it ?
> 
> After a SOURCE_CHANGE event is received, G_FMT returns the *new* format,
> including colorimetry. This will become the active format once the drain
> operation finished.
> 
> If that's not clear from the spec, then I need to improve it.
> 
> Regards,
> 
> 	Hans
> 
> > > +
> > > +    .. important::
> > > +
> > > +       Any client query issued after the decoder queues the event will return
> > > +       values applying to the stream after the resolution change, including
> > > +       queue formats, selection rectangles and controls.
> > > +
> > > +2.  The decoder will then process and decode all remaining buffers from before
> > > +    the resolution change point.
> > > +
> > > +    * The last buffer from before the change must be marked with the
> > > +      ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
> > > +
> > > +    .. warning::
> > > +
> > > +       The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
> > > +       = 0) and in that case it must be ignored by the client, as it does not
> > > +       contain a decoded frame.
> > > +
> > > +    .. note::
> > > +
> > > +       Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
> > > +       with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
> > > +       :c:func:`VIDIOC_DQBUF`.
> > > +
> > > +The client must continue the sequence as described below to continue the
> > > +decoding process.
> > > +
> > > +1.  Dequeue the source change event.
> > > +
> > > +    .. important::
> > > +
> > > +       A source change triggers an implicit decoder drain, similar to the
> > > +       explicit `Drain` sequence. The decoder is stopped after it completes.
> > > +       The decoding process must be resumed with either a pair of calls to
> > > +       :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> > > +       ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
> > > +       ``V4L2_DEC_CMD_START`` command.
> > > +
> > > +2.  Continue with the `Capture setup` sequence.
> > > +
> > > +.. note::
> > > +
> > > +   During the resolution change sequence, the ``OUTPUT`` queue must remain
> > > +   streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
> > > +   abort the sequence and initiate a seek.
> > > +
> > > +   In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
> > > +   queue and this remains true for the duration of the entire resolution change
> > > +   sequence as well.
> > > +
> > > +   The client should, for best performance and simplicity, keep queuing/dequeuing
> > > +   buffers to/from the ``OUTPUT`` queue even while processing this sequence.
> > > +
> > > +Drain
> > > +=====
> > > +
> > > +To ensure that all queued ``OUTPUT`` buffers have been processed and related
> > > +``CAPTURE`` buffers are given to the client, the client must follow the drain
> > > +sequence described below. After the drain sequence ends, the client has
> > > +received all decoded frames for all ``OUTPUT`` buffers queued before the
> > > +sequence was started.
> > > +
> > > +1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
> > > +
> > > +   * **Required fields:**
> > > +
> > > +     ``cmd``
> > > +         set to ``V4L2_DEC_CMD_STOP``.
> > > +
> > > +     ``flags``
> > > +         set to 0.
> > > +
> > > +     ``pts``
> > > +         set to 0.
> > > +
> > > +   .. warning::
> > > +
> > > +      The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
> > > +      queues are streaming. For compatibility reasons, the call to
> > > +      :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
> > > +      not streaming, but at the same time it will not initiate the `Drain`
> > > +      sequence and so the steps described below would not be applicable.
> > > +
> > > +2. Any ``OUTPUT`` buffers queued by the client before the
> > > +   :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
> > > +   normal. The client must continue to handle both queues independently,
> > > +   similarly to normal decode operation. This includes:
> > > +
> > > +   * handling any operations triggered as a result of processing those buffers,
> > > +     such as the `Dynamic resolution change` sequence, before continuing with
> > > +     the drain sequence,
> > > +
> > > +   * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
> > > +     ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
> > > +
> > > +     .. warning::
> > > +
> > > +        The last buffer may be empty (with :c:type:`v4l2_buffer`
> > > +        ``bytesused`` = 0) and in that case it must be ignored by the client,
> > > +        as it does not contain a decoded frame.
> > > +
> > > +     .. note::
> > > +
> > > +        Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
> > > +        marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
> > > +        :c:func:`VIDIOC_DQBUF`.
> > > +
> > > +   * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
> > > +     before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
> > > +
> > > +   * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
> > > +
> > > +   .. note::
> > > +
> > > +      For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
> > > +      event when the last frame has been decoded and all frames are ready to be
> > > +      dequeued. It is a deprecated behavior and the client must not rely on it.
> > > +      The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
> > > +
> > > +3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
> > > +   are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
> > > +   stopped and it will accept, but not process, any newly queued ``OUTPUT``
> > > +   buffers until the client issues any of the following operations:
> > > +
> > > +   * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
> > > +     operation normally, with all the state from before the drain,
> > > +
> > > +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> > > +     ``CAPTURE`` queue - the decoder will resume the operation normally,
> > > +     however any ``CAPTURE`` buffers still in the queue will be returned to the
> > > +     client,
> > > +
> > > +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> > > +     ``OUTPUT`` queue - any pending source buffers will be returned to the
> > > +     client and the `Seek` sequence will be triggered.
> > > +
> > > +.. note::
> > > +
> > > +   Once the drain sequence is initiated, the client needs to drive it to
> > > +   completion, as described by the steps above, unless it aborts the process by
> > > +   issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
> > > +   queues.  The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
> > > +   ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
> > > +   will fail with -EBUSY error code if attempted.
> > > +
> > > +   Although mandatory, the availability of decoder commands may be queried
> > > +   using :c:func:`VIDIOC_TRY_DECODER_CMD`.
> > > +
> > > +End of stream
> > > +=============
> > > +
> > > +If the decoder encounters an end of stream marking in the stream, the decoder
> > > +will initiate the `Drain` sequence, which the client must handle as described
> > > +above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
> > > +
> > > +Commit points
> > > +=============
> > > +
> > > +Setting formats and allocating buffers trigger changes in the behavior of the
> > > +decoder.
> > > +
> > > +1. Setting the format on the ``OUTPUT`` queue may change the set of formats
> > > +   supported/advertised on the ``CAPTURE`` queue. In particular, it also means
> > > +   that the ``CAPTURE`` format may be reset and the client must not rely on the
> > > +   previously set format being preserved.
> > > +
> > > +2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
> > > +   supported for the current ``OUTPUT`` format.
> > > +
> > > +3. Setting the format on the ``CAPTURE`` queue does not change the list of
> > > +   formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
> > > +   format that is not supported for the currently selected ``OUTPUT`` format
> > > +   will result in the decoder adjusting the requested ``CAPTURE`` format to a
> > > +   supported one.
> > > +
> > > +4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
> > > +   supported coded formats, irrespectively of the current ``CAPTURE`` format.
> > > +
> > > +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
> > > +   the client must not change the format on the ``OUTPUT`` queue. Drivers will
> > > +   return the -EBUSY error code for any such format change attempt.
> > > +
> > > +To summarize, setting formats and allocation must always start with the
> > > +``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
> > > +set of supported formats for the ``CAPTURE`` queue.
> > > diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> > > index 67a980818dc8..caa05f5f6380 100644
> > > --- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
> > > +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> > > @@ -39,4 +39,10 @@ file handle is visible through another file handle).
> > >  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
> > > diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> > > index 71eebfc6d853..caf14e440447 100644
> > > --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> > > +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> > > @@ -39,6 +39,11 @@ Single-planar format structure
> > >  	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.
> > > diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> > > index 004ec00db6bd..97015b9b40b8 100644
> > > --- a/Documentation/media/uapi/v4l/v4l2.rst
> > > +++ b/Documentation/media/uapi/v4l/v4l2.rst
> > > @@ -60,6 +60,10 @@ Authors, in alphabetical order:
> > >  
> > >    - 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.
> > > @@ -68,6 +72,10 @@ Authors, in alphabetical order:
> > >  
> > >    - 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.
> > > @@ -92,7 +100,7 @@ Authors, in alphabetical order:
> > >  
> > >    - 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.
> > > diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> > > index ccf83b05afa7..57f0066f4cff 100644
> > > --- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> > > +++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> > > @@ -56,14 +56,16 @@ The ``cmd`` field must contain the command code. Some commands use the
> > >  
> > >  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}|
> > > @@ -167,26 +169,32 @@ introduced in Linux 3.3.
> > >  	``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
> > > @@ -209,6 +217,11 @@ 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.
> > >  
> > > +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.
> > >  

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Hans Verkuil]

On 6/12/19 2:25 AM, Nicolas Dufresne wrote:
> Le mardi 11 juin 2019 à 10:29 +0200, Hans Verkuil a écrit :
>> On 6/10/19 9:54 PM, Nicolas Dufresne wrote:
>>> Hi Hans,
>>>
>>> I went through it, and I think we are close to ready. Unfortunately, I
>>> believe the SOURCE_CHANGE event is still under specified. There was a
>>> post recently to try and add a new flag for changes in color space
>>> which is not included here. We are also missing a workflow for changes
>>> that don't affect the allocation but will affect the rendering on a
>>> display (like colorimetry). Userspace needs to know at which frames
>>> these parameter changes in order to signal that to the following
>>> processing block. I think we must have a plane for this.
>>
>> Yes, we need a new flag for the SOURCE_CHANGE event to indicate colorimetry
>> changes. That's actually useful for e.g. HDMI receivers as well.
>>
>> But I don't see why that should make much of a change to the spec: you still
>> have to drain the capture queue, the only difference is that you don't need
>> to reallocate buffers, you can just restart the decoder.
> 
> I don't think you need to drain the queue if the change is just
> metadata that have no impact on the buffers allocation or layout. I
> think we should have a way to communicate these changed while
> streaming. Basically, something like the event, but serialized.

I guess we can extend the struct v4l2_event_src_change and add a buffer
index field to indicate at which capture buffer index the colorimetry
change takes effect. Then there is no need for draining.

In the future when we create replacement streaming ioctls and have a
new, larger struct v4l2_buffer, then we can add the colorimetry information
there as well.

Regards,

	Hans

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Hans Verkuil]

On 6/12/19 8:49 AM, Hans Verkuil wrote:
> On 6/12/19 2:25 AM, Nicolas Dufresne wrote:
>> Le mardi 11 juin 2019 à 10:29 +0200, Hans Verkuil a écrit :
>>> On 6/10/19 9:54 PM, Nicolas Dufresne wrote:
>>>> Hi Hans,
>>>>
>>>> I went through it, and I think we are close to ready. Unfortunately, I
>>>> believe the SOURCE_CHANGE event is still under specified. There was a
>>>> post recently to try and add a new flag for changes in color space
>>>> which is not included here. We are also missing a workflow for changes
>>>> that don't affect the allocation but will affect the rendering on a
>>>> display (like colorimetry). Userspace needs to know at which frames
>>>> these parameter changes in order to signal that to the following
>>>> processing block. I think we must have a plane for this.
>>>
>>> Yes, we need a new flag for the SOURCE_CHANGE event to indicate colorimetry
>>> changes. That's actually useful for e.g. HDMI receivers as well.
>>>
>>> But I don't see why that should make much of a change to the spec: you still
>>> have to drain the capture queue, the only difference is that you don't need
>>> to reallocate buffers, you can just restart the decoder.
>>
>> I don't think you need to drain the queue if the change is just
>> metadata that have no impact on the buffers allocation or layout. I
>> think we should have a way to communicate these changed while
>> streaming. Basically, something like the event, but serialized.
> 
> I guess we can extend the struct v4l2_event_src_change and add a buffer
> index field to indicate at which capture buffer index the colorimetry
> change takes effect. Then there is no need for draining.

Just wanted to add something here: for now drivers can just use SOURCE_CHANGE
+ drain if they detect a colorimetry change. It's not as efficient as it can
be, but it will work. Applications can easily check that they don't need to
reallocate since the reported sizeimage will be the same for the old and new
formats.

> In the future when we create replacement streaming ioctls and have a
> new, larger struct v4l2_buffer, then we can add the colorimetry information
> there as well.

When this is in place, then it would make sense to add a V4L2_EVENT_SRC_CH_COLORIMETRY
flag that just indicates that something changed w.r.t. colorimetry.

We DO need this flag for HDMI receivers in any case.

Regards,

	Hans

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Maxime Jourdan]

On Tue, Jun 11, 2019 at 10:29 AM Hans Verkuil <hverkuil-cisco@xs4all.nl> wrote:
>
> On 6/10/19 9:54 PM, Nicolas Dufresne wrote:
> > Hi Hans,
> >
> > I went through it, and I think we are close to ready. Unfortunately, I
> > believe the SOURCE_CHANGE event is still under specified. There was a
> > post recently to try and add a new flag for changes in color space
> > which is not included here. We are also missing a workflow for changes
> > that don't affect the allocation but will affect the rendering on a
> > display (like colorimetry). Userspace needs to know at which frames
> > these parameter changes in order to signal that to the following
> > processing block. I think we must have a plane for this.
>
> Yes, we need a new flag for the SOURCE_CHANGE event to indicate colorimetry
> changes. That's actually useful for e.g. HDMI receivers as well.
>
> But I don't see why that should make much of a change to the spec: you still
> have to drain the capture queue, the only difference is that you don't need
> to reallocate buffers, you can just restart the decoder.
>
> My intention was to get this spec in first, then extend it once we have a new
> colorimetry change flag.
>
> >
> > Another aspect, I'd like if we could relax a bit the bits about dynamic
> > resolutions, making some space for the "static resolution" cases.
> > Something to keep in mind, these "static resolution" HW might not be
> > able to inform userspace of the display size of the picture, we should
> > check with Maxime what happens with the Amlogic.
>
> I've asked him about that in another email thread:
>
> https://www.mail-archive.com/linux-media@vger.kernel.org/msg147652.html
>
> Maxime, related to that: can the amlogic detect midstream colorimetry
> changes? Or is that also impossible?
>

Hi Hans, Nicolas,

The SOURCE_CHANGE limitations on amlogic are related to older
compression standards. I'm focusing on H264, HEVC, VP9 which will all
be able to properly report resolution changes (and probing at init).
Currently, older codecs such as MPEG 1/2 require userspace to probe
the coded resolution itself and set it to the driver via S_FMT, but
there is no indication from the driver about that. See the series
about the FIXED_RESOLUTION fmt flag for what I had in mind but isn't
that great of a solution..

When it comes to colorimetry, I don't believe I saw anything in the
vendor SDK that relates to probing colorspace (e.g bt.709/bt.601
etc.).

@Nicolas: is this information embedded in a SEI packet or SPS/PPS when
it comes to H264 ?

> >
> > Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> >> From: Tomasz Figa <tfiga@chromium.org>
> >>
> >> Due to complexity of the video decoding process, the V4L2 drivers of
> >> stateful decoder hardware require specific sequences of V4L2 API calls
> >> to be followed. These include capability enumeration, initialization,
> >> decoding, seek, pause, dynamic resolution change, drain and end of
> >> stream.
> >>
> >> Specifics of the above have been discussed during Media Workshops at
> >> LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
> >> Conference Europe 2014 in Düsseldorf. The de facto Codec API that
> >> originated at those events was later implemented by the drivers we already
> >> have merged in mainline, such as s5p-mfc or coda.
> >>
> >> The only thing missing was the real specification included as a part of
> >> Linux Media documentation. Fix it now and document the decoder part of
> >> the Codec API.
> >>
> >> Signed-off-by: Tomasz Figa <tfiga@chromium.org>
> >> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> >> ---
> >>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
> >>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
> >>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
> >>  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
> >>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
> >>  5 files changed, 1132 insertions(+), 16 deletions(-)
> >>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> >>
> >> diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst
> >> new file mode 100644
> >> index 000000000000..b106f2d97c48
> >> --- /dev/null
> >> +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
> >> @@ -0,0 +1,1084 @@
> >> +.. SPDX-License-Identifier: GPL-2.0
> >> +
> >> +.. _decoder:
> >> +
> >> +*************************************************
> >> +Memory-to-memory Stateful Video Decoder Interface
> >> +*************************************************
> >> +
> >> +A stateful video decoder takes complete chunks of the bitstream (e.g. Annex-B
> >> +H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
> >
> > (minor, may ignore)
> > This isn't very precise, do we expect to document this per-format ? I
> > think we should maybe say "a complete frame of the bitstream", that
> > being said, I think stateful CODEC should be allowed to implement the
> > per-slice/per-frame control we are adding to stateless CODEC. Maybe
> > something like "documented complete chunks of bitstream" ?
> >
> >> +display order. The decoder is expected not to require any additional information
> >> +from the client to process these buffers.
> >> +
> >> +Performing software parsing, processing etc. of the stream in the driver in
> >> +order to support this interface is strongly discouraged. In case such
> >> +operations are needed, use of the Stateless Video Decoder Interface (in
> >> +development) is strongly advised.
> >> +
> >> +Conventions and notation used in this document
> >> +==============================================
> >> +
> >> +1. The general V4L2 API rules apply if not specified in this document
> >> +   otherwise.
> >> +
> >> +2. The meaning of words "must", "may", "should", etc. is as per `RFC
> >> +   2119 <https://tools.ietf.org/html/rfc2119>`_.
> >> +
> >> +3. All steps not marked "optional" are required.
> >> +
> >> +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
> >> +   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
> >> +   unless specified otherwise.
> >> +
> >> +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
> >> +   used interchangeably with multi-planar API, unless specified otherwise,
> >> +   depending on decoder capabilities and following the general V4L2 guidelines.
> >> +
> >> +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
> >> +   [0..2]: i = 0, 1, 2.
> >> +
> >> +7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
> >> +   queue containing data that resulted from processing buffer A.
> >> +
> >> +.. _decoder-glossary:
> >> +
> >> +Glossary
> >> +========
> >> +
> >> +CAPTURE
> >> +   the destination buffer queue; for decoders, the queue of buffers containing
> >> +   decoded frames; for encoders, the queue of buffers containing an encoded
> >> +   bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
> >> +   ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
> >> +   into ``CAPTURE`` buffers.
> >> +
> >> +client
> >> +   the application communicating with the decoder or encoder implementing
> >> +   this interface.
> >> +
> >> +coded format
> >> +   encoded/compressed video bitstream format (e.g. H.264, VP8, etc.); see
> >> +   also: raw format.
> >> +
> >> +coded height
> >> +   height for given coded resolution.
> >> +
> >> +coded resolution
> >> +   stream resolution in pixels aligned to codec and hardware requirements;
> >> +   typically visible resolution rounded up to full macroblocks;
> >> +   see also: visible resolution.
> >> +
> >> +coded width
> >> +   width for given coded resolution.
> >> +
> >> +decode order
> >> +   the order in which frames are decoded; may differ from display order if the
> >> +   coded format includes a feature of frame reordering; for decoders,
> >> +   ``OUTPUT`` buffers must be queued by the client in decode order; for
> >> +   encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
> >> +
> >> +destination
> >> +   data resulting from the decode process; see ``CAPTURE``.
> >> +
> >> +display order
> >> +   the order in which frames must be displayed; for encoders, ``OUTPUT``
> >> +   buffers must be queued by the client in display order; for decoders,
> >> +   ``CAPTURE`` buffers must be returned by the decoder in display order.
> >> +
> >> +DPB
> >> +   Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
> >> +   raw frame available for reference in further decoding steps.
> >> +
> >> +EOS
> >> +   end of stream.
> >> +
> >> +IDR
> >> +   Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
> >> +   stream, which clears the list of earlier reference frames (DPBs).
> >> +
> >> +keyframe
> >> +   an encoded frame that does not reference frames decoded earlier, i.e.
> >> +   can be decoded fully on its own.
> >> +
> >> +macroblock
> >> +   a processing unit in image and video compression formats based on linear
> >> +   block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
> >> +   popular codecs the size is 16x16 samples (pixels).
> >> +
> >> +OUTPUT
> >> +   the source buffer queue; for decoders, the queue of buffers containing
> >> +   an encoded bitstream; for encoders, the queue of buffers containing raw
> >> +   frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
> >> +   ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
> >> +   from ``OUTPUT`` buffers.
> >> +
> >> +PPS
> >> +   Picture Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> >> +
> >> +raw format
> >> +   uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
> >> +
> >> +resume point
> >> +   a point in the bitstream from which decoding may start/continue, without
> >> +   any previous state/data present, e.g.: a keyframe (VP8/VP9) or
> >> +   SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
> >> +   of a new stream, or to resume decoding after a seek.
> >> +
> >> +source
> >> +   data fed to the decoder or encoder; see ``OUTPUT``.
> >> +
> >> +source height
> >> +   height in pixels for given source resolution; relevant to encoders only.
> >> +
> >> +source resolution
> >> +   resolution in pixels of source frames being source to the encoder and
> >> +   subject to further cropping to the bounds of visible resolution; relevant to
> >> +   encoders only.
> >> +
> >> +source width
> >> +   width in pixels for given source resolution; relevant to encoders only.
> >> +
> >> +SPS
> >> +   Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> >> +
> >> +stream metadata
> >> +   additional (non-visual) information contained inside encoded bitstream;
> >> +   for example: coded resolution, visible resolution, codec profile.
> >> +
> >> +visible height
> >> +   height for given visible resolution; display height.
> >> +
> >> +visible resolution
> >> +   stream resolution of the visible picture, in pixels, to be used for
> >> +   display purposes; must be smaller or equal to coded resolution;
> >> +   display resolution.
> >> +
> >> +visible width
> >> +   width for given visible resolution; display width.
> >> +
> >> +State machine
> >> +=============
> >> +
> >> +.. kernel-render:: DOT
> >> +   :alt: DOT digraph of decoder state machine
> >> +   :caption: Decoder state machine
> >> +
> >> +   digraph decoder_state_machine {
> >> +       node [shape = doublecircle, label="Decoding"] Decoding;
> >> +
> >> +       node [shape = circle, label="Initialization"] Initialization;
> >> +       node [shape = circle, label="Capture\nsetup"] CaptureSetup;
> >> +       node [shape = circle, label="Dynamic\nresolution\nchange"] ResChange;
> >> +       node [shape = circle, label="Stopped"] Stopped;
> >> +       node [shape = circle, label="Drain"] Drain;
> >> +       node [shape = circle, label="Seek"] Seek;
> >> +       node [shape = circle, label="End of stream"] EoS;
> >> +
> >> +       node [shape = point]; qi
> >> +       qi -> Initialization [ label = "open()" ];
> >> +
> >> +       Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> >> +
> >> +       CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
> >> +
> >> +       Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
> >> +       Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
> >> +       Decoding -> EoS [ label = "EoS mark\nin the stream" ];
> >> +       Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> >> +       Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
> >> +       Decoding -> Decoding;
> >> +
> >> +       ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> >> +       ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> >> +
> >> +       EoS -> Drain [ label = "Implicit\ndrain" ];
> >> +
> >> +       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
> >> +       Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> >> +
> >> +       Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
> >> +       Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
> >> +
> >> +       Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
> >> +       Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> >> +   }
> >> +
> >> +Querying capabilities
> >> +=====================
> >> +
> >> +1. To enumerate the set of coded formats supported by the decoder, the
> >> +   client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
> >> +
> >> +   * The full set of supported formats will be returned, regardless of the
> >> +     format set on ``CAPTURE``.
> >> +
> >> +2. To enumerate the set of supported raw formats, the client may call
> >> +   :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
> >> +
> >> +   * Only the formats supported for the format currently active on ``OUTPUT``
> >> +     will be returned.
> >> +
> >> +   * In order to enumerate raw formats supported by a given coded format,
> >> +     the client must first set that coded format on ``OUTPUT`` and then
> >> +     enumerate formats on ``CAPTURE``.
> >> +
> >> +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
> >> +   resolutions for a given format, passing desired pixel format in
> >> +   :c:type:`v4l2_frmsizeenum` ``pixel_format``.
> >> +
> >> +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
> >> +     format will include all possible coded resolutions supported by the
> >> +     decoder for given coded pixel format.
> >> +
> >> +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
> >> +     will include all possible frame buffer resolutions supported by the
> >> +     decoder for given raw pixel format and the coded format currently set on
> >> +     ``OUTPUT``.
> >> +
> >> +4. Supported profiles and levels for the coded format currently set on
> >> +   ``OUTPUT``, if applicable, may be queried using their respective controls
> >> +   via :c:func:`VIDIOC_QUERYCTRL`.
> >> +
> >> +Initialization
> >> +==============
> >> +
> >> +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
> >> +
> >> +   * **Required fields:**
> >> +
> >> +     ``type``
> >> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> >> +
> >> +     ``pixelformat``
> >> +         a coded pixel format.
> >> +
> >> +     ``width``, ``height``
> >> +         coded resolution of the stream; required only if it cannot be parsed
> >> +         from the stream for the given coded format; otherwise the decoder will
> >> +         use this resolution as a placeholder resolution that will likely change
> >> +         as soon as it can parse the actual coded resolution from the stream.
> >> +
> >> +     ``sizeimage``
> >> +         desired size of ``OUTPUT`` buffers; the decoder may adjust it to
> >> +         match hardware requirements.
> >> +
> >> +     other fields
> >> +         follow standard semantics.
> >> +
> >> +   * **Return fields:**
> >> +
> >> +     ``sizeimage``
> >> +         adjusted size of ``OUTPUT`` buffers.
> >> +
> >> +   * The ``CAPTURE`` format will be updated with an appropriate frame buffer
> >> +     resolution instantly based on the width and height returned by
> >> +     :c:func:`VIDIOC_S_FMT`.
> >> +     However, for coded formats that include stream resolution information,
> >> +     after the decoder is done parsing the information from the stream, it will
> >> +     update the ``CAPTURE`` format with new values and signal a source change
> >> +     event, regardless of whether they match the values set by the client or
> >> +     not.
> >> +
> >> +   .. important::
> >> +
> >> +      Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
> >> +      format. How the new ``CAPTURE`` format is determined is up to the decoder
> >> +      and the client must ensure it matches its needs afterwards.
> >> +
> >> +2.  Allocate source (bitstream) buffers via :c:func:`VIDIOC_REQBUFS` on
> >> +    ``OUTPUT``.
> >> +
> >> +    * **Required fields:**
> >> +
> >> +      ``count``
> >> +          requested number of buffers to allocate; greater than zero.
> >> +
> >> +      ``type``
> >> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> >> +
> >> +      ``memory``
> >> +          follows standard semantics.
> >> +
> >> +    * **Return fields:**
> >> +
> >> +      ``count``
> >> +          the actual number of buffers allocated.
> >> +
> >> +    .. warning::
> >> +
> >> +       The actual number of allocated buffers may differ from the ``count``
> >> +       given. The client must check the updated value of ``count`` after the
> >> +       call returns.
> >> +
> >> +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
> >> +    used to have more control over buffer allocation.
> >> +
> >> +    * **Required fields:**
> >> +
> >> +      ``count``
> >> +          requested number of buffers to allocate; greater than zero.
> >> +
> >> +      ``type``
> >> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> >> +
> >> +      ``memory``
> >> +          follows standard semantics.
> >> +
> >> +      ``format``
> >> +          follows standard semantics.
> >> +
> >> +    * **Return fields:**
> >> +
> >> +      ``count``
> >> +          adjusted to the number of allocated buffers.
> >> +
> >> +    .. warning::
> >> +
> >> +       The actual number of allocated buffers may differ from the ``count``
> >> +       given. The client must check the updated value of ``count`` after the
> >> +       call returns.
> >> +
> >> +3.  Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
> >> +
> >> +4.  **This step only applies to coded formats that contain resolution information
> >> +    in the stream.** Continue queuing/dequeuing bitstream buffers to/from the
> >> +    ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
> >> +    buffers will be processed and returned to the client in order, until
> >> +    required metadata to configure the ``CAPTURE`` queue are found. This is
> >> +    indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
> >> +    ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> >> +
> >> +    * It is not an error if the first buffer does not contain enough data for
> >> +      this to occur. Processing of the buffers will continue as long as more
> >> +      data is needed.
> >> +
> >> +    * If data in a buffer that triggers the event is required to decode the
> >> +      first frame, it will not be returned to the client, until the
> >> +      initialization sequence completes and the frame is decoded.
> >> +
> >> +    * If the client has not set the coded resolution of the stream on its own,
> >> +      calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
> >> +      :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
> >> +      queue will not return the real values for the stream until a
> >> +      ``V4L2_EVENT_SOURCE_CHANGE`` event is signaled.
> >> +
> >> +    .. important::
> >> +
> >> +       Any client query issued after the decoder queues the event will return
> >> +       values applying to the just parsed stream, including queue formats,
> >> +       selection rectangles and controls.
> >> +
> >> +    .. note::
> >> +
> >> +       A client capable of acquiring stream parameters from the bitstream on
> >> +       its own may attempt to set the width and height of the ``OUTPUT`` format
> >> +       to non-zero values matching the coded size of the stream, skip this step
> >> +       and continue with the `Capture setup` sequence. However, it must not
> >> +       rely on any driver queries regarding stream parameters, such as
> >> +       selection rectangles and controls, since the decoder has not parsed them
> >> +       from the stream yet. If the values configured by the client do not match
> >> +       those parsed by the decoder, a `Dynamic resolution change` will be
> >> +       triggered to reconfigure them.
> >> +
> >> +    .. note::
> >> +
> >> +       No decoded frames are produced during this phase.
> >> +
> >> +5.  Continue with the `Capture setup` sequence.
> >> +
> >> +Capture setup
> >> +=============
> >> +
> >> +1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
> >> +    destination buffers parsed/decoded from the bitstream.
> >> +
> >> +    * **Required fields:**
> >> +
> >> +      ``type``
> >> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> >> +
> >> +    * **Return fields:**
> >> +
> >> +      ``width``, ``height``
> >> +          frame buffer resolution for the decoded frames.
> >> +
> >> +      ``pixelformat``
> >> +          pixel format for decoded frames.
> >> +
> >> +      ``num_planes`` (for _MPLANE ``type`` only)
> >> +          number of planes for pixelformat.
> >> +
> >> +      ``sizeimage``, ``bytesperline``
> >> +          as per standard semantics; matching frame buffer format.
> >> +
> >> +    .. note::
> >> +
> >> +       The value of ``pixelformat`` may be any pixel format supported by the
> >> +       decoder for the current stream. The decoder should choose a
> >> +       preferred/optimal format for the default configuration. For example, a
> >> +       YUV format may be preferred over an RGB format if an additional
> >> +       conversion step would be required for the latter.
> >> +
> >> +2.  **Optional.** Acquire the visible resolution via
> >> +    :c:func:`VIDIOC_G_SELECTION`.
> >> +
> >> +    * **Required fields:**
> >> +
> >> +      ``type``
> >> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> >> +
> >> +      ``target``
> >> +          set to ``V4L2_SEL_TGT_COMPOSE``.
> >> +
> >> +    * **Return fields:**
> >> +
> >> +      ``r.left``, ``r.top``, ``r.width``, ``r.height``
> >> +          the visible rectangle; it must fit within the frame buffer resolution
> >> +          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> >> +
> >> +    * The following selection targets are supported on ``CAPTURE``:
> >> +
> >> +      ``V4L2_SEL_TGT_CROP_BOUNDS``
> >> +          corresponds to the coded resolution of the stream.
> >> +
> >> +      ``V4L2_SEL_TGT_CROP_DEFAULT``
> >> +          the rectangle covering the part of the ``CAPTURE`` buffer that
> >> +          contains meaningful picture data (visible area); width and height
> >> +          will be equal to the visible resolution of the stream.
> >> +
> >> +      ``V4L2_SEL_TGT_CROP``
> >> +          the rectangle within the coded resolution to be output to
> >> +          ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
> >> +          hardware without additional compose/scaling capabilities.
> >> +
> >> +      ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
> >> +          the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
> >> +          frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
> >> +          hardware does not support compose/scaling.
> >> +
> >> +      ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
> >> +          equal to ``V4L2_SEL_TGT_CROP``.
> >> +
> >> +      ``V4L2_SEL_TGT_COMPOSE``
> >> +          the rectangle inside a ``CAPTURE`` buffer into which the cropped
> >> +          frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> >> +          read-only on hardware without additional compose/scaling capabilities.
> >> +
> >> +      ``V4L2_SEL_TGT_COMPOSE_PADDED``
> >> +          the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
> >> +          hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
> >> +          write padding pixels.
> >> +
> >> +    .. warning::
> >> +
> >> +       The values are guaranteed to be meaningful only after the decoder
> >> +       successfully parses the stream metadata. The client must not rely on the
> >> +       query before that happens.
> >> +
> >> +3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
> >> +    the ``CAPTURE`` queue. Once the stream information is parsed and known, the
> >> +    client may use this ioctl to discover which raw formats are supported for
> >> +    given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
> >> +
> >> +    .. important::
> >> +
> >> +       The decoder will return only formats supported for the currently
> >> +       established coded format, as per the ``OUTPUT`` format and/or stream
> >> +       metadata parsed in this initialization sequence, even if more formats
> >> +       may be supported by the decoder in general. In other words, the set
> >> +       returned will be a subset of the initial query mentioned in the
> >> +       `Querying capabilities` section.
> >> +
> >> +       For example, a decoder may support YUV and RGB formats for resolutions
> >> +       1920x1088 and lower, but only YUV for higher resolutions (due to
> >> +       hardware limitations). After parsing a resolution of 1920x1088 or lower,
> >> +       :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
> >> +       but after parsing resolution higher than 1920x1088, the decoder will not
> >> +       return RGB, unsupported for this resolution.
> >> +
> >> +       However, subsequent resolution change event triggered after
> >> +       discovering a resolution change within the same stream may switch
> >> +       the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
> >> +       would return RGB formats again in that case.
> >> +
> >> +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
> >> +    ``CAPTURE`` queue. The client may choose a different format than
> >> +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
> >> +
> >> +    * **Required fields:**
> >> +
> >> +      ``type``
> >> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> >> +
> >> +      ``pixelformat``
> >> +          a raw pixel format.
> >> +
> >> +   * Setting the ``CAPTURE`` format will reset the compose selection rectangles
> >> +     to their default values, based on the new resolution, as described in the
> >> +     previous step.
> >> +
> >> +5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
> >> +   the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
> >> +   scaling capabilities.
> >> +
> >> +   * **Required fields:**
> >> +
> >> +     ``type``
> >> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> >> +
> >> +     ``target``
> >> +         set to ``V4L2_SEL_TGT_COMPOSE``.
> >> +
> >> +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> >> +         the rectangle inside a ``CAPTURE`` buffer into which the cropped
> >> +         frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> >> +         read-only on hardware without additional compose/scaling capabilities.
> >> +
> >> +   * **Return fields:**
> >> +
> >> +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> >> +         the visible rectangle; it must fit within the frame buffer resolution
> >> +         returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> >> +
> >> +   .. warning::
> >> +
> >> +      The decoder may adjust the compose rectangle to the nearest
> >> +      supported one to meet codec and hardware requirements. The client needs
> >> +      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
> >> +
> >> +6.  If all the following conditions are met, the client may resume the decoding
> >> +    instantly:
> >> +
> >> +    * ``sizeimage`` of the new format (determined in previous steps) is less
> >> +      than or equal to the size of currently allocated buffers,
> >> +
> >> +    * the number of buffers currently allocated is greater than or equal to the
> >> +      minimum number of buffers acquired in previous steps. To fulfill this
> >> +      requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
> >> +      buffers.
> >> +
> >> +    In that case, the remaining steps do not apply and the client may resume
> >> +    the decoding by one of the following actions:
> >> +
> >> +    * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
> >> +      with the ``V4L2_DEC_CMD_START`` command,
> >> +
> >> +    * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
> >> +      on the ``CAPTURE`` queue.
> >> +
> >> +    However, if the client intends to change the buffer set, to lower
> >> +    memory usage or for any other reasons, it may be achieved by following
> >> +    the steps below.
> >> +
> >> +7.  **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
> >> +    buffers on the ``CAPTURE`` queue until a buffer marked with the
> >> +    ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
> >> +
> >> +8.  **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
> >> +    on the ``CAPTURE`` queue to stop streaming.
> >> +
> >> +    .. warning::
> >> +
> >> +       The ``OUTPUT`` queue must remain streaming. Calling
> >> +       :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
> >> +       seek.
> >> +
> >> +9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
> >> +    buffers using :c:func:`VIDIOC_REQBUFS`.
> >> +
> >> +    * **Required fields:**
> >> +
> >> +      ``count``
> >> +          set to 0.
> >> +
> >> +      ``type``
> >> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> >> +
> >> +      ``memory``
> >> +          follows standard semantics.
> >> +
> >> +10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
> >> +    ``CAPTURE`` queue.
> >> +
> >> +    * **Required fields:**
> >> +
> >> +      ``count``
> >> +          requested number of buffers to allocate; greater than zero.
> >> +
> >> +      ``type``
> >> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> >> +
> >> +      ``memory``
> >> +          follows standard semantics.
> >> +
> >> +    * **Return fields:**
> >> +
> >> +      ``count``
> >> +          actual number of buffers allocated.
> >> +
> >> +    .. warning::
> >> +
> >> +       The actual number of allocated buffers may differ from the ``count``
> >> +       given. The client must check the updated value of ``count`` after the
> >> +       call returns.
> >> +
> >> +    .. note::
> >> +
> >> +       To allocate more than the minimum number of buffers (for pipeline
> >> +       depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
> >> +       control to get the minimum number of buffers required, and pass the
> >> +       obtained value plus the number of additional buffers needed in the
> >> +       ``count`` field to :c:func:`VIDIOC_REQBUFS`.
> >> +
> >> +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
> >> +    used to have more control over buffer allocation. For example, by
> >> +    allocating buffers larger than the current ``CAPTURE`` format, future
> >> +    resolution changes can be accommodated.
> >> +
> >> +    * **Required fields:**
> >> +
> >> +      ``count``
> >> +          requested number of buffers to allocate; greater than zero.
> >> +
> >> +      ``type``
> >> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> >> +
> >> +      ``memory``
> >> +          follows standard semantics.
> >> +
> >> +      ``format``
> >> +          a format representing the maximum framebuffer resolution to be
> >> +          accommodated by newly allocated buffers.
> >> +
> >> +    * **Return fields:**
> >> +
> >> +      ``count``
> >> +          adjusted to the number of allocated buffers.
> >> +
> >> +    .. warning::
> >> +
> >> +        The actual number of allocated buffers may differ from the ``count``
> >> +        given. The client must check the updated value of ``count`` after the
> >> +        call returns.
> >> +
> >> +    .. note::
> >> +
> >> +       To allocate buffers for a format different than parsed from the stream
> >> +       metadata, the client must proceed as follows, before the metadata
> >> +       parsing is initiated:
> >> +
> >> +       * set width and height of the ``OUTPUT`` format to desired coded resolution to
> >> +         let the decoder configure the ``CAPTURE`` format appropriately,
> >> +
> >> +       * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
> >> +         until this step.
> >> +
> >> +       The format obtained in the query may be then used with
> >> +       :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
> >> +
> >> +11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
> >> +    frames.
> >> +
> >> +Decoding
> >> +========
> >> +
> >> +This state is reached after the `Capture setup` sequence finishes successfully.
> >> +In this state, the client queues and dequeues buffers to both queues via
> >> +:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
> >> +semantics.
> >> +
> >> +The content of the source ``OUTPUT`` buffers depends on the active coded pixel
> >> +format and may be affected by codec-specific extended controls, as stated in
> >> +the documentation of each format.
> >> +
> >> +Both queues operate independently, following the standard behavior of V4L2
> >> +buffer queues and memory-to-memory devices. In addition, the order of decoded
> >> +frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
> >> +coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
> >> +format, e.g. frame reordering.
> >> +
> >> +The client must not assume any direct relationship between ``CAPTURE``
> >> +and ``OUTPUT`` buffers and any specific timing of buffers becoming
> >> +available to dequeue. Specifically:
> >> +
> >> +* a buffer queued to ``OUTPUT`` may result in no buffers being produced
> >> +  on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
> >> +  metadata syntax structures are present in it),
> >> +
> >> +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
> >> +  on ``CAPTURE`` (if the encoded data contained more than one frame, or if
> >> +  returning a decoded frame allowed the decoder to return a frame that
> >> +  preceded it in decode, but succeeded it in the display order),
> >> +
> >> +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
> >> +  ``CAPTURE`` later into decode process, and/or after processing further
> >> +  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
> >> +  reordering is used,
> >> +
> >> +* buffers may become available on the ``CAPTURE`` queue without additional
> >> +  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
> >> +  ``OUTPUT`` buffers queued in the past whose decoding results are only
> >> +  available at later time, due to specifics of the decoding process.
> >> +
> >> +.. note::
> >> +
> >> +   To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
> >> +   originated from, the client can set the ``timestamp`` field of the
> >> +   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
> >> +   ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
> >> +   will have their ``timestamp`` field set to the same value when dequeued.
> >> +
> >> +   In addition to the straightforward case of one ``OUTPUT`` buffer producing
> >> +   one ``CAPTURE`` buffer, the following cases are defined:
> >> +
> >> +   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
> >> +     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
> >> +
> >> +   * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
> >> +     the ``OUTPUT`` buffer queued last will be copied.
> >> +
> >> +   * the decoding order differs from the display order (i.e. the ``CAPTURE``
> >> +     buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
> >> +     timestamps will not retain the order of ``OUTPUT`` timestamps.
> >> +
> >> +During the decoding, the decoder may initiate one of the special sequences, as
> >> +listed below. The sequences will result in the decoder returning all the
> >> +``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
> >> +before the sequence started. Last of the buffers will have the
> >> +``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
> >> +must check if there is any pending event and:
> >> +
> >> +* if a ``V4L2_EVENT_SOURCE_CHANGE`` event is pending, the `Dynamic resolution
> >> +  change` sequence needs to be followed,
> >> +
> >> +* if a ``V4L2_EVENT_EOS`` event is pending, the `End of stream` sequence needs
> >> +  to be followed.
> >> +
> >> +Some of the sequences can be intermixed with each other and need to be handled
> >> +as they happen. The exact operation is documented for each sequence.
> >> +
> >> +Should a decoding error occur, it will be reported to the client with the level
> >> +of details depending on the decoder capabilities. Specifically:
> >> +
> >> +* the CAPTURE buffer that contains the results of the failed decode operation
> >> +  will be returned with the V4L2_BUF_FLAG_ERROR flag set,
> >> +
> >> +* if the decoder is able to precisely report the OUTPUT buffer that triggered
> >> +  the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
> >> +  set.
> >> +
> >> +In case of a fatal failure that does not allow the decoding to continue, any
> >> +further operations on corresponding decoder file handle will return the -EIO
> >> +error code. The client may close the file handle and open a new one, or
> >> +alternatively reinitialize the instance by stopping streaming on both queues,
> >> +releasing all buffers and performing the Initialization sequence again.
> >> +
> >> +Seek
> >> +====
> >> +
> >> +Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
> >> +The seek does not require any specific operation on the ``CAPTURE`` queue, but
> >> +it may be affected as per normal decoder operation.
> >> +
> >> +1. Stop the ``OUTPUT`` queue to begin the seek sequence via
> >> +   :c:func:`VIDIOC_STREAMOFF`.
> >> +
> >> +   * **Required fields:**
> >> +
> >> +     ``type``
> >> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> >> +
> >> +   * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
> >> +     treated as returned to the client (following standard semantics).
> >> +
> >> +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`
> >> +
> >> +   * **Required fields:**
> >> +
> >> +     ``type``
> >> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> >> +
> >> +   * The decoder will start accepting new source bitstream buffers after the
> >> +     call returns.
> >> +
> >> +3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
> >> +   queue until a suitable resume point is found.
> >> +
> >> +   .. note::
> >> +
> >> +      There is no requirement to begin queuing coded data starting exactly
> >> +      from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
> >> +      buffers will be processed and returned to the client until a suitable
> >> +      resume point is found.  While looking for a resume point, the decoder
> >> +      should not produce any decoded frames into ``CAPTURE`` buffers.
> >> +
> >> +      Some hardware is known to mishandle seeks to a non-resume point. Such an
> >> +      operation may result in an unspecified number of corrupted decoded frames
> >> +      being made available on the ``CAPTURE`` queue. Drivers must ensure that
> >> +      no fatal decoding errors or crashes occur, and implement any necessary
> >> +      handling and workarounds for hardware issues related to seek operations.
> >> +
> >> +   .. warning::
> >> +
> >> +      In case of the H.264/HEVC codec, the client must take care not to seek
> >> +      over a change of SPS/PPS. Even though the target frame could be a
> >> +      keyframe, the stale SPS/PPS inside decoder state would lead to undefined
> >> +      results when decoding. Although the decoder must handle that case without
> >> +      a crash or a fatal decode error, the client must not expect a sensible
> >> +      decode output.
> >> +
> >> +      If the hardware can detect such corrupted decoded frames, then
> >> +      corresponding buffers will be returned to the client with the
> >> +      V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
> >> +      description of decode error reporting.
> >> +
> >> +4. After a resume point is found, the decoder will start returning ``CAPTURE``
> >> +   buffers containing decoded frames.
> >> +
> >> +.. important::
> >> +
> >> +   A seek may result in the `Dynamic resolution change` sequence being
> >> +   initiated, due to the seek target having decoding parameters different from
> >> +   the part of the stream decoded before the seek. The sequence must be handled
> >> +   as per normal decoder operation.
> >> +
> >> +.. warning::
> >> +
> >> +   It is not specified when the ``CAPTURE`` queue starts producing buffers
> >> +   containing decoded data from the ``OUTPUT`` buffers queued after the seek,
> >> +   as it operates independently from the ``OUTPUT`` queue.
> >> +
> >> +   The decoder may return a number of remaining ``CAPTURE`` buffers containing
> >> +   decoded frames originating from the ``OUTPUT`` buffers queued before the
> >> +   seek sequence is performed.
> >> +
> >> +   The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
> >> +   ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
> >> +   queued before the seek sequence may have matching ``CAPTURE`` buffers
> >> +   produced.  For example, given the sequence of operations on the
> >> +   ``OUTPUT`` queue:
> >> +
> >> +     QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
> >> +
> >> +   any of the following results on the ``CAPTURE`` queue is allowed:
> >> +
> >> +     {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}.
> >> +
> >> +   To determine the CAPTURE buffer containing the first decoded frame after the
> >> +   seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
> >> +   buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
> >> +   decoder.
> >> +
> >> +.. note::
> >> +
> >> +   To achieve instantaneous seek, the client may restart streaming on the
> >> +   ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
> >> +
> >> +Dynamic resolution change
> >> +=========================
> >> +
> >> +Streams that include resolution metadata in the bitstream may require switching
> >> +to a different resolution during the decoding.
> >> +
> >> +The sequence starts when the decoder detects a coded frame with one or more of
> >> +the following parameters different from those previously established (and
> >> +reflected by corresponding queries):
> >> +
> >> +* coded resolution (``OUTPUT`` width and height),
> >> +
> >> +* visible resolution (selection rectangles),
> >> +
> >> +* the minimum number of buffers needed for decoding.
> >> +
> >> +Whenever that happens, the decoder must proceed as follows:
> >> +
> >> +1.  After encountering a resolution change in the stream, the decoder sends a
> >> +    ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
> >> +    ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> >
> > What about a format changes that does now affect the resolution, like a
> > pixel format change ? Also, what about changes that don't require a
>
> A pixel format change always implies a resolution change.
>
> > reallocation ? Like a change in the colorimetry parameters ? I don't
> > think the spec need to initially cover it all, but we need to make sure
> > there is a mechanism for userspace to know at which frames to read back
> > the new format (G_FMT). Maybe we need both an event and a buffer flag
> > to mark it ?
>
> After a SOURCE_CHANGE event is received, G_FMT returns the *new* format,
> including colorimetry. This will become the active format once the drain
> operation finished.
>
> If that's not clear from the spec, then I need to improve it.
>
> Regards,
>
>         Hans
>
> >
> >> +
> >> +    .. important::
> >> +
> >> +       Any client query issued after the decoder queues the event will return
> >> +       values applying to the stream after the resolution change, including
> >> +       queue formats, selection rectangles and controls.
> >> +
> >> +2.  The decoder will then process and decode all remaining buffers from before
> >> +    the resolution change point.
> >> +
> >> +    * The last buffer from before the change must be marked with the
> >> +      ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
> >> +
> >> +    .. warning::
> >> +
> >> +       The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
> >> +       = 0) and in that case it must be ignored by the client, as it does not
> >> +       contain a decoded frame.
> >> +
> >> +    .. note::
> >> +
> >> +       Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
> >> +       with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
> >> +       :c:func:`VIDIOC_DQBUF`.
> >> +
> >> +The client must continue the sequence as described below to continue the
> >> +decoding process.
> >> +
> >> +1.  Dequeue the source change event.
> >> +
> >> +    .. important::
> >> +
> >> +       A source change triggers an implicit decoder drain, similar to the
> >> +       explicit `Drain` sequence. The decoder is stopped after it completes.
> >> +       The decoding process must be resumed with either a pair of calls to
> >> +       :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> >> +       ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
> >> +       ``V4L2_DEC_CMD_START`` command.
> >> +
> >> +2.  Continue with the `Capture setup` sequence.
> >> +
> >> +.. note::
> >> +
> >> +   During the resolution change sequence, the ``OUTPUT`` queue must remain
> >> +   streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
> >> +   abort the sequence and initiate a seek.
> >> +
> >> +   In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
> >> +   queue and this remains true for the duration of the entire resolution change
> >> +   sequence as well.
> >> +
> >> +   The client should, for best performance and simplicity, keep queuing/dequeuing
> >> +   buffers to/from the ``OUTPUT`` queue even while processing this sequence.
> >> +
> >> +Drain
> >> +=====
> >> +
> >> +To ensure that all queued ``OUTPUT`` buffers have been processed and related
> >> +``CAPTURE`` buffers are given to the client, the client must follow the drain
> >> +sequence described below. After the drain sequence ends, the client has
> >> +received all decoded frames for all ``OUTPUT`` buffers queued before the
> >> +sequence was started.
> >> +
> >> +1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
> >> +
> >> +   * **Required fields:**
> >> +
> >> +     ``cmd``
> >> +         set to ``V4L2_DEC_CMD_STOP``.
> >> +
> >> +     ``flags``
> >> +         set to 0.
> >> +
> >> +     ``pts``
> >> +         set to 0.
> >> +
> >> +   .. warning::
> >> +
> >> +      The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
> >> +      queues are streaming. For compatibility reasons, the call to
> >> +      :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
> >> +      not streaming, but at the same time it will not initiate the `Drain`
> >> +      sequence and so the steps described below would not be applicable.
> >> +
> >> +2. Any ``OUTPUT`` buffers queued by the client before the
> >> +   :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
> >> +   normal. The client must continue to handle both queues independently,
> >> +   similarly to normal decode operation. This includes:
> >> +
> >> +   * handling any operations triggered as a result of processing those buffers,
> >> +     such as the `Dynamic resolution change` sequence, before continuing with
> >> +     the drain sequence,
> >> +
> >> +   * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
> >> +     ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
> >> +
> >> +     .. warning::
> >> +
> >> +        The last buffer may be empty (with :c:type:`v4l2_buffer`
> >> +        ``bytesused`` = 0) and in that case it must be ignored by the client,
> >> +        as it does not contain a decoded frame.
> >> +
> >> +     .. note::
> >> +
> >> +        Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
> >> +        marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
> >> +        :c:func:`VIDIOC_DQBUF`.
> >> +
> >> +   * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
> >> +     before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
> >> +
> >> +   * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
> >> +
> >> +   .. note::
> >> +
> >> +      For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
> >> +      event when the last frame has been decoded and all frames are ready to be
> >> +      dequeued. It is a deprecated behavior and the client must not rely on it.
> >> +      The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
> >> +
> >> +3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
> >> +   are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
> >> +   stopped and it will accept, but not process, any newly queued ``OUTPUT``
> >> +   buffers until the client issues any of the following operations:
> >> +
> >> +   * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
> >> +     operation normally, with all the state from before the drain,
> >> +
> >> +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> >> +     ``CAPTURE`` queue - the decoder will resume the operation normally,
> >> +     however any ``CAPTURE`` buffers still in the queue will be returned to the
> >> +     client,
> >> +
> >> +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> >> +     ``OUTPUT`` queue - any pending source buffers will be returned to the
> >> +     client and the `Seek` sequence will be triggered.
> >> +
> >> +.. note::
> >> +
> >> +   Once the drain sequence is initiated, the client needs to drive it to
> >> +   completion, as described by the steps above, unless it aborts the process by
> >> +   issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
> >> +   queues.  The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
> >> +   ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
> >> +   will fail with -EBUSY error code if attempted.
> >> +
> >> +   Although mandatory, the availability of decoder commands may be queried
> >> +   using :c:func:`VIDIOC_TRY_DECODER_CMD`.
> >> +
> >> +End of stream
> >> +=============
> >> +
> >> +If the decoder encounters an end of stream marking in the stream, the decoder
> >> +will initiate the `Drain` sequence, which the client must handle as described
> >> +above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
> >> +
> >> +Commit points
> >> +=============
> >> +
> >> +Setting formats and allocating buffers trigger changes in the behavior of the
> >> +decoder.
> >> +
> >> +1. Setting the format on the ``OUTPUT`` queue may change the set of formats
> >> +   supported/advertised on the ``CAPTURE`` queue. In particular, it also means
> >> +   that the ``CAPTURE`` format may be reset and the client must not rely on the
> >> +   previously set format being preserved.
> >> +
> >> +2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
> >> +   supported for the current ``OUTPUT`` format.
> >> +
> >> +3. Setting the format on the ``CAPTURE`` queue does not change the list of
> >> +   formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
> >> +   format that is not supported for the currently selected ``OUTPUT`` format
> >> +   will result in the decoder adjusting the requested ``CAPTURE`` format to a
> >> +   supported one.
> >> +
> >> +4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
> >> +   supported coded formats, irrespectively of the current ``CAPTURE`` format.
> >> +
> >> +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
> >> +   the client must not change the format on the ``OUTPUT`` queue. Drivers will
> >> +   return the -EBUSY error code for any such format change attempt.
> >> +
> >> +To summarize, setting formats and allocation must always start with the
> >> +``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
> >> +set of supported formats for the ``CAPTURE`` queue.
> >> diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> >> index 67a980818dc8..caa05f5f6380 100644
> >> --- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
> >> +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> >> @@ -39,4 +39,10 @@ file handle is visible through another file handle).
> >>  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
> >> diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> >> index 71eebfc6d853..caf14e440447 100644
> >> --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> >> +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> >> @@ -39,6 +39,11 @@ Single-planar format structure
> >>      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.
> >> diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> >> index 004ec00db6bd..97015b9b40b8 100644
> >> --- a/Documentation/media/uapi/v4l/v4l2.rst
> >> +++ b/Documentation/media/uapi/v4l/v4l2.rst
> >> @@ -60,6 +60,10 @@ Authors, in alphabetical order:
> >>
> >>    - 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.
> >> @@ -68,6 +72,10 @@ Authors, in alphabetical order:
> >>
> >>    - 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.
> >> @@ -92,7 +100,7 @@ Authors, in alphabetical order:
> >>
> >>    - 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.
> >> diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> >> index ccf83b05afa7..57f0066f4cff 100644
> >> --- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> >> +++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> >> @@ -56,14 +56,16 @@ The ``cmd`` field must contain the command code. Some commands use the
> >>
> >>  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}|
> >> @@ -167,26 +169,32 @@ introduced in Linux 3.3.
> >>      ``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
> >> @@ -209,6 +217,11 @@ 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.
> >>
> >> +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.
> >>
>

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Nicolas Dufresne]

[-- Attachment #1: Type: text/plain, Size: 67941 bytes --]

Le lundi 15 juillet 2019 à 14:12 +0200, Maxime Jourdan a écrit :
> On Tue, Jun 11, 2019 at 10:29 AM Hans Verkuil <hverkuil-cisco@xs4all.nl> wrote:
> > On 6/10/19 9:54 PM, Nicolas Dufresne wrote:
> > > Hi Hans,
> > > 
> > > I went through it, and I think we are close to ready. Unfortunately, I
> > > believe the SOURCE_CHANGE event is still under specified. There was a
> > > post recently to try and add a new flag for changes in color space
> > > which is not included here. We are also missing a workflow for changes
> > > that don't affect the allocation but will affect the rendering on a
> > > display (like colorimetry). Userspace needs to know at which frames
> > > these parameter changes in order to signal that to the following
> > > processing block. I think we must have a plane for this.
> > 
> > Yes, we need a new flag for the SOURCE_CHANGE event to indicate colorimetry
> > changes. That's actually useful for e.g. HDMI receivers as well.
> > 
> > But I don't see why that should make much of a change to the spec: you still
> > have to drain the capture queue, the only difference is that you don't need
> > to reallocate buffers, you can just restart the decoder.
> > 
> > My intention was to get this spec in first, then extend it once we have a new
> > colorimetry change flag.
> > 
> > > Another aspect, I'd like if we could relax a bit the bits about dynamic
> > > resolutions, making some space for the "static resolution" cases.
> > > Something to keep in mind, these "static resolution" HW might not be
> > > able to inform userspace of the display size of the picture, we should
> > > check with Maxime what happens with the Amlogic.
> > 
> > I've asked him about that in another email thread:
> > 
> > https://www.mail-archive.com/linux-media@vger.kernel.org/msg147652.html
> > 
> > Maxime, related to that: can the amlogic detect midstream colorimetry
> > changes? Or is that also impossible?
> > 
> 
> Hi Hans, Nicolas,
> 
> The SOURCE_CHANGE limitations on amlogic are related to older
> compression standards. I'm focusing on H264, HEVC, VP9 which will all
> be able to properly report resolution changes (and probing at init).
> Currently, older codecs such as MPEG 1/2 require userspace to probe
> the coded resolution itself and set it to the driver via S_FMT, but
> there is no indication from the driver about that. See the series
> about the FIXED_RESOLUTION fmt flag for what I had in mind but isn't
> that great of a solution..
> 
> When it comes to colorimetry, I don't believe I saw anything in the
> vendor SDK that relates to probing colorspace (e.g bt.709/bt.601
> etc.).
> 
> @Nicolas: is this information embedded in a SEI packet or SPS/PPS when
> it comes to H264 ?

It seems it a VUI parameter, which is part of the active SPS.

> 
> > > Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> > > > From: Tomasz Figa <tfiga@chromium.org>
> > > > 
> > > > Due to complexity of the video decoding process, the V4L2 drivers of
> > > > stateful decoder hardware require specific sequences of V4L2 API calls
> > > > to be followed. These include capability enumeration, initialization,
> > > > decoding, seek, pause, dynamic resolution change, drain and end of
> > > > stream.
> > > > 
> > > > Specifics of the above have been discussed during Media Workshops at
> > > > LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
> > > > Conference Europe 2014 in Düsseldorf. The de facto Codec API that
> > > > originated at those events was later implemented by the drivers we already
> > > > have merged in mainline, such as s5p-mfc or coda.
> > > > 
> > > > The only thing missing was the real specification included as a part of
> > > > Linux Media documentation. Fix it now and document the decoder part of
> > > > the Codec API.
> > > > 
> > > > Signed-off-by: Tomasz Figa <tfiga@chromium.org>
> > > > Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> > > > ---
> > > >  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
> > > >  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
> > > >  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
> > > >  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
> > > >  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
> > > >  5 files changed, 1132 insertions(+), 16 deletions(-)
> > > >  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> > > > 
> > > > diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst
> > > > new file mode 100644
> > > > index 000000000000..b106f2d97c48
> > > > --- /dev/null
> > > > +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
> > > > @@ -0,0 +1,1084 @@
> > > > +.. SPDX-License-Identifier: GPL-2.0
> > > > +
> > > > +.. _decoder:
> > > > +
> > > > +*************************************************
> > > > +Memory-to-memory Stateful Video Decoder Interface
> > > > +*************************************************
> > > > +
> > > > +A stateful video decoder takes complete chunks of the bitstream (e.g. Annex-B
> > > > +H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
> > > 
> > > (minor, may ignore)
> > > This isn't very precise, do we expect to document this per-format ? I
> > > think we should maybe say "a complete frame of the bitstream", that
> > > being said, I think stateful CODEC should be allowed to implement the
> > > per-slice/per-frame control we are adding to stateless CODEC. Maybe
> > > something like "documented complete chunks of bitstream" ?
> > > 
> > > > +display order. The decoder is expected not to require any additional information
> > > > +from the client to process these buffers.
> > > > +
> > > > +Performing software parsing, processing etc. of the stream in the driver in
> > > > +order to support this interface is strongly discouraged. In case such
> > > > +operations are needed, use of the Stateless Video Decoder Interface (in
> > > > +development) is strongly advised.
> > > > +
> > > > +Conventions and notation used in this document
> > > > +==============================================
> > > > +
> > > > +1. The general V4L2 API rules apply if not specified in this document
> > > > +   otherwise.
> > > > +
> > > > +2. The meaning of words "must", "may", "should", etc. is as per `RFC
> > > > +   2119 <https://tools.ietf.org/html/rfc2119>`_.
> > > > +
> > > > +3. All steps not marked "optional" are required.
> > > > +
> > > > +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
> > > > +   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
> > > > +   unless specified otherwise.
> > > > +
> > > > +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
> > > > +   used interchangeably with multi-planar API, unless specified otherwise,
> > > > +   depending on decoder capabilities and following the general V4L2 guidelines.
> > > > +
> > > > +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
> > > > +   [0..2]: i = 0, 1, 2.
> > > > +
> > > > +7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
> > > > +   queue containing data that resulted from processing buffer A.
> > > > +
> > > > +.. _decoder-glossary:
> > > > +
> > > > +Glossary
> > > > +========
> > > > +
> > > > +CAPTURE
> > > > +   the destination buffer queue; for decoders, the queue of buffers containing
> > > > +   decoded frames; for encoders, the queue of buffers containing an encoded
> > > > +   bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
> > > > +   ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
> > > > +   into ``CAPTURE`` buffers.
> > > > +
> > > > +client
> > > > +   the application communicating with the decoder or encoder implementing
> > > > +   this interface.
> > > > +
> > > > +coded format
> > > > +   encoded/compressed video bitstream format (e.g. H.264, VP8, etc.); see
> > > > +   also: raw format.
> > > > +
> > > > +coded height
> > > > +   height for given coded resolution.
> > > > +
> > > > +coded resolution
> > > > +   stream resolution in pixels aligned to codec and hardware requirements;
> > > > +   typically visible resolution rounded up to full macroblocks;
> > > > +   see also: visible resolution.
> > > > +
> > > > +coded width
> > > > +   width for given coded resolution.
> > > > +
> > > > +decode order
> > > > +   the order in which frames are decoded; may differ from display order if the
> > > > +   coded format includes a feature of frame reordering; for decoders,
> > > > +   ``OUTPUT`` buffers must be queued by the client in decode order; for
> > > > +   encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
> > > > +
> > > > +destination
> > > > +   data resulting from the decode process; see ``CAPTURE``.
> > > > +
> > > > +display order
> > > > +   the order in which frames must be displayed; for encoders, ``OUTPUT``
> > > > +   buffers must be queued by the client in display order; for decoders,
> > > > +   ``CAPTURE`` buffers must be returned by the decoder in display order.
> > > > +
> > > > +DPB
> > > > +   Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
> > > > +   raw frame available for reference in further decoding steps.
> > > > +
> > > > +EOS
> > > > +   end of stream.
> > > > +
> > > > +IDR
> > > > +   Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
> > > > +   stream, which clears the list of earlier reference frames (DPBs).
> > > > +
> > > > +keyframe
> > > > +   an encoded frame that does not reference frames decoded earlier, i.e.
> > > > +   can be decoded fully on its own.
> > > > +
> > > > +macroblock
> > > > +   a processing unit in image and video compression formats based on linear
> > > > +   block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
> > > > +   popular codecs the size is 16x16 samples (pixels).
> > > > +
> > > > +OUTPUT
> > > > +   the source buffer queue; for decoders, the queue of buffers containing
> > > > +   an encoded bitstream; for encoders, the queue of buffers containing raw
> > > > +   frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
> > > > +   ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
> > > > +   from ``OUTPUT`` buffers.
> > > > +
> > > > +PPS
> > > > +   Picture Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> > > > +
> > > > +raw format
> > > > +   uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
> > > > +
> > > > +resume point
> > > > +   a point in the bitstream from which decoding may start/continue, without
> > > > +   any previous state/data present, e.g.: a keyframe (VP8/VP9) or
> > > > +   SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
> > > > +   of a new stream, or to resume decoding after a seek.
> > > > +
> > > > +source
> > > > +   data fed to the decoder or encoder; see ``OUTPUT``.
> > > > +
> > > > +source height
> > > > +   height in pixels for given source resolution; relevant to encoders only.
> > > > +
> > > > +source resolution
> > > > +   resolution in pixels of source frames being source to the encoder and
> > > > +   subject to further cropping to the bounds of visible resolution; relevant to
> > > > +   encoders only.
> > > > +
> > > > +source width
> > > > +   width in pixels for given source resolution; relevant to encoders only.
> > > > +
> > > > +SPS
> > > > +   Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> > > > +
> > > > +stream metadata
> > > > +   additional (non-visual) information contained inside encoded bitstream;
> > > > +   for example: coded resolution, visible resolution, codec profile.
> > > > +
> > > > +visible height
> > > > +   height for given visible resolution; display height.
> > > > +
> > > > +visible resolution
> > > > +   stream resolution of the visible picture, in pixels, to be used for
> > > > +   display purposes; must be smaller or equal to coded resolution;
> > > > +   display resolution.
> > > > +
> > > > +visible width
> > > > +   width for given visible resolution; display width.
> > > > +
> > > > +State machine
> > > > +=============
> > > > +
> > > > +.. kernel-render:: DOT
> > > > +   :alt: DOT digraph of decoder state machine
> > > > +   :caption: Decoder state machine
> > > > +
> > > > +   digraph decoder_state_machine {
> > > > +       node [shape = doublecircle, label="Decoding"] Decoding;
> > > > +
> > > > +       node [shape = circle, label="Initialization"] Initialization;
> > > > +       node [shape = circle, label="Capture\nsetup"] CaptureSetup;
> > > > +       node [shape = circle, label="Dynamic\nresolution\nchange"] ResChange;
> > > > +       node [shape = circle, label="Stopped"] Stopped;
> > > > +       node [shape = circle, label="Drain"] Drain;
> > > > +       node [shape = circle, label="Seek"] Seek;
> > > > +       node [shape = circle, label="End of stream"] EoS;
> > > > +
> > > > +       node [shape = point]; qi
> > > > +       qi -> Initialization [ label = "open()" ];
> > > > +
> > > > +       Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> > > > +
> > > > +       CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
> > > > +
> > > > +       Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
> > > > +       Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
> > > > +       Decoding -> EoS [ label = "EoS mark\nin the stream" ];
> > > > +       Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > > +       Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
> > > > +       Decoding -> Decoding;
> > > > +
> > > > +       ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> > > > +       ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > > +
> > > > +       EoS -> Drain [ label = "Implicit\ndrain" ];
> > > > +
> > > > +       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
> > > > +       Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > > +
> > > > +       Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
> > > > +       Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
> > > > +
> > > > +       Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
> > > > +       Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > > +   }
> > > > +
> > > > +Querying capabilities
> > > > +=====================
> > > > +
> > > > +1. To enumerate the set of coded formats supported by the decoder, the
> > > > +   client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
> > > > +
> > > > +   * The full set of supported formats will be returned, regardless of the
> > > > +     format set on ``CAPTURE``.
> > > > +
> > > > +2. To enumerate the set of supported raw formats, the client may call
> > > > +   :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
> > > > +
> > > > +   * Only the formats supported for the format currently active on ``OUTPUT``
> > > > +     will be returned.
> > > > +
> > > > +   * In order to enumerate raw formats supported by a given coded format,
> > > > +     the client must first set that coded format on ``OUTPUT`` and then
> > > > +     enumerate formats on ``CAPTURE``.
> > > > +
> > > > +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
> > > > +   resolutions for a given format, passing desired pixel format in
> > > > +   :c:type:`v4l2_frmsizeenum` ``pixel_format``.
> > > > +
> > > > +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
> > > > +     format will include all possible coded resolutions supported by the
> > > > +     decoder for given coded pixel format.
> > > > +
> > > > +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
> > > > +     will include all possible frame buffer resolutions supported by the
> > > > +     decoder for given raw pixel format and the coded format currently set on
> > > > +     ``OUTPUT``.
> > > > +
> > > > +4. Supported profiles and levels for the coded format currently set on
> > > > +   ``OUTPUT``, if applicable, may be queried using their respective controls
> > > > +   via :c:func:`VIDIOC_QUERYCTRL`.
> > > > +
> > > > +Initialization
> > > > +==============
> > > > +
> > > > +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
> > > > +
> > > > +   * **Required fields:**
> > > > +
> > > > +     ``type``
> > > > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > > +
> > > > +     ``pixelformat``
> > > > +         a coded pixel format.
> > > > +
> > > > +     ``width``, ``height``
> > > > +         coded resolution of the stream; required only if it cannot be parsed
> > > > +         from the stream for the given coded format; otherwise the decoder will
> > > > +         use this resolution as a placeholder resolution that will likely change
> > > > +         as soon as it can parse the actual coded resolution from the stream.
> > > > +
> > > > +     ``sizeimage``
> > > > +         desired size of ``OUTPUT`` buffers; the decoder may adjust it to
> > > > +         match hardware requirements.
> > > > +
> > > > +     other fields
> > > > +         follow standard semantics.
> > > > +
> > > > +   * **Return fields:**
> > > > +
> > > > +     ``sizeimage``
> > > > +         adjusted size of ``OUTPUT`` buffers.
> > > > +
> > > > +   * The ``CAPTURE`` format will be updated with an appropriate frame buffer
> > > > +     resolution instantly based on the width and height returned by
> > > > +     :c:func:`VIDIOC_S_FMT`.
> > > > +     However, for coded formats that include stream resolution information,
> > > > +     after the decoder is done parsing the information from the stream, it will
> > > > +     update the ``CAPTURE`` format with new values and signal a source change
> > > > +     event, regardless of whether they match the values set by the client or
> > > > +     not.
> > > > +
> > > > +   .. important::
> > > > +
> > > > +      Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
> > > > +      format. How the new ``CAPTURE`` format is determined is up to the decoder
> > > > +      and the client must ensure it matches its needs afterwards.
> > > > +
> > > > +2.  Allocate source (bitstream) buffers via :c:func:`VIDIOC_REQBUFS` on
> > > > +    ``OUTPUT``.
> > > > +
> > > > +    * **Required fields:**
> > > > +
> > > > +      ``count``
> > > > +          requested number of buffers to allocate; greater than zero.
> > > > +
> > > > +      ``type``
> > > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > > +
> > > > +      ``memory``
> > > > +          follows standard semantics.
> > > > +
> > > > +    * **Return fields:**
> > > > +
> > > > +      ``count``
> > > > +          the actual number of buffers allocated.
> > > > +
> > > > +    .. warning::
> > > > +
> > > > +       The actual number of allocated buffers may differ from the ``count``
> > > > +       given. The client must check the updated value of ``count`` after the
> > > > +       call returns.
> > > > +
> > > > +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
> > > > +    used to have more control over buffer allocation.
> > > > +
> > > > +    * **Required fields:**
> > > > +
> > > > +      ``count``
> > > > +          requested number of buffers to allocate; greater than zero.
> > > > +
> > > > +      ``type``
> > > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > > +
> > > > +      ``memory``
> > > > +          follows standard semantics.
> > > > +
> > > > +      ``format``
> > > > +          follows standard semantics.
> > > > +
> > > > +    * **Return fields:**
> > > > +
> > > > +      ``count``
> > > > +          adjusted to the number of allocated buffers.
> > > > +
> > > > +    .. warning::
> > > > +
> > > > +       The actual number of allocated buffers may differ from the ``count``
> > > > +       given. The client must check the updated value of ``count`` after the
> > > > +       call returns.
> > > > +
> > > > +3.  Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
> > > > +
> > > > +4.  **This step only applies to coded formats that contain resolution information
> > > > +    in the stream.** Continue queuing/dequeuing bitstream buffers to/from the
> > > > +    ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
> > > > +    buffers will be processed and returned to the client in order, until
> > > > +    required metadata to configure the ``CAPTURE`` queue are found. This is
> > > > +    indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
> > > > +    ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> > > > +
> > > > +    * It is not an error if the first buffer does not contain enough data for
> > > > +      this to occur. Processing of the buffers will continue as long as more
> > > > +      data is needed.
> > > > +
> > > > +    * If data in a buffer that triggers the event is required to decode the
> > > > +      first frame, it will not be returned to the client, until the
> > > > +      initialization sequence completes and the frame is decoded.
> > > > +
> > > > +    * If the client has not set the coded resolution of the stream on its own,
> > > > +      calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
> > > > +      :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
> > > > +      queue will not return the real values for the stream until a
> > > > +      ``V4L2_EVENT_SOURCE_CHANGE`` event is signaled.
> > > > +
> > > > +    .. important::
> > > > +
> > > > +       Any client query issued after the decoder queues the event will return
> > > > +       values applying to the just parsed stream, including queue formats,
> > > > +       selection rectangles and controls.
> > > > +
> > > > +    .. note::
> > > > +
> > > > +       A client capable of acquiring stream parameters from the bitstream on
> > > > +       its own may attempt to set the width and height of the ``OUTPUT`` format
> > > > +       to non-zero values matching the coded size of the stream, skip this step
> > > > +       and continue with the `Capture setup` sequence. However, it must not
> > > > +       rely on any driver queries regarding stream parameters, such as
> > > > +       selection rectangles and controls, since the decoder has not parsed them
> > > > +       from the stream yet. If the values configured by the client do not match
> > > > +       those parsed by the decoder, a `Dynamic resolution change` will be
> > > > +       triggered to reconfigure them.
> > > > +
> > > > +    .. note::
> > > > +
> > > > +       No decoded frames are produced during this phase.
> > > > +
> > > > +5.  Continue with the `Capture setup` sequence.
> > > > +
> > > > +Capture setup
> > > > +=============
> > > > +
> > > > +1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
> > > > +    destination buffers parsed/decoded from the bitstream.
> > > > +
> > > > +    * **Required fields:**
> > > > +
> > > > +      ``type``
> > > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > > +
> > > > +    * **Return fields:**
> > > > +
> > > > +      ``width``, ``height``
> > > > +          frame buffer resolution for the decoded frames.
> > > > +
> > > > +      ``pixelformat``
> > > > +          pixel format for decoded frames.
> > > > +
> > > > +      ``num_planes`` (for _MPLANE ``type`` only)
> > > > +          number of planes for pixelformat.
> > > > +
> > > > +      ``sizeimage``, ``bytesperline``
> > > > +          as per standard semantics; matching frame buffer format.
> > > > +
> > > > +    .. note::
> > > > +
> > > > +       The value of ``pixelformat`` may be any pixel format supported by the
> > > > +       decoder for the current stream. The decoder should choose a
> > > > +       preferred/optimal format for the default configuration. For example, a
> > > > +       YUV format may be preferred over an RGB format if an additional
> > > > +       conversion step would be required for the latter.
> > > > +
> > > > +2.  **Optional.** Acquire the visible resolution via
> > > > +    :c:func:`VIDIOC_G_SELECTION`.
> > > > +
> > > > +    * **Required fields:**
> > > > +
> > > > +      ``type``
> > > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > > +
> > > > +      ``target``
> > > > +          set to ``V4L2_SEL_TGT_COMPOSE``.
> > > > +
> > > > +    * **Return fields:**
> > > > +
> > > > +      ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > > > +          the visible rectangle; it must fit within the frame buffer resolution
> > > > +          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> > > > +
> > > > +    * The following selection targets are supported on ``CAPTURE``:
> > > > +
> > > > +      ``V4L2_SEL_TGT_CROP_BOUNDS``
> > > > +          corresponds to the coded resolution of the stream.
> > > > +
> > > > +      ``V4L2_SEL_TGT_CROP_DEFAULT``
> > > > +          the rectangle covering the part of the ``CAPTURE`` buffer that
> > > > +          contains meaningful picture data (visible area); width and height
> > > > +          will be equal to the visible resolution of the stream.
> > > > +
> > > > +      ``V4L2_SEL_TGT_CROP``
> > > > +          the rectangle within the coded resolution to be output to
> > > > +          ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
> > > > +          hardware without additional compose/scaling capabilities.
> > > > +
> > > > +      ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
> > > > +          the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
> > > > +          frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
> > > > +          hardware does not support compose/scaling.
> > > > +
> > > > +      ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
> > > > +          equal to ``V4L2_SEL_TGT_CROP``.
> > > > +
> > > > +      ``V4L2_SEL_TGT_COMPOSE``
> > > > +          the rectangle inside a ``CAPTURE`` buffer into which the cropped
> > > > +          frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> > > > +          read-only on hardware without additional compose/scaling capabilities.
> > > > +
> > > > +      ``V4L2_SEL_TGT_COMPOSE_PADDED``
> > > > +          the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
> > > > +          hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
> > > > +          write padding pixels.
> > > > +
> > > > +    .. warning::
> > > > +
> > > > +       The values are guaranteed to be meaningful only after the decoder
> > > > +       successfully parses the stream metadata. The client must not rely on the
> > > > +       query before that happens.
> > > > +
> > > > +3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
> > > > +    the ``CAPTURE`` queue. Once the stream information is parsed and known, the
> > > > +    client may use this ioctl to discover which raw formats are supported for
> > > > +    given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
> > > > +
> > > > +    .. important::
> > > > +
> > > > +       The decoder will return only formats supported for the currently
> > > > +       established coded format, as per the ``OUTPUT`` format and/or stream
> > > > +       metadata parsed in this initialization sequence, even if more formats
> > > > +       may be supported by the decoder in general. In other words, the set
> > > > +       returned will be a subset of the initial query mentioned in the
> > > > +       `Querying capabilities` section.
> > > > +
> > > > +       For example, a decoder may support YUV and RGB formats for resolutions
> > > > +       1920x1088 and lower, but only YUV for higher resolutions (due to
> > > > +       hardware limitations). After parsing a resolution of 1920x1088 or lower,
> > > > +       :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
> > > > +       but after parsing resolution higher than 1920x1088, the decoder will not
> > > > +       return RGB, unsupported for this resolution.
> > > > +
> > > > +       However, subsequent resolution change event triggered after
> > > > +       discovering a resolution change within the same stream may switch
> > > > +       the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
> > > > +       would return RGB formats again in that case.
> > > > +
> > > > +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
> > > > +    ``CAPTURE`` queue. The client may choose a different format than
> > > > +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
> > > > +
> > > > +    * **Required fields:**
> > > > +
> > > > +      ``type``
> > > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > > +
> > > > +      ``pixelformat``
> > > > +          a raw pixel format.
> > > > +
> > > > +   * Setting the ``CAPTURE`` format will reset the compose selection rectangles
> > > > +     to their default values, based on the new resolution, as described in the
> > > > +     previous step.
> > > > +
> > > > +5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
> > > > +   the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
> > > > +   scaling capabilities.
> > > > +
> > > > +   * **Required fields:**
> > > > +
> > > > +     ``type``
> > > > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > > +
> > > > +     ``target``
> > > > +         set to ``V4L2_SEL_TGT_COMPOSE``.
> > > > +
> > > > +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > > > +         the rectangle inside a ``CAPTURE`` buffer into which the cropped
> > > > +         frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> > > > +         read-only on hardware without additional compose/scaling capabilities.
> > > > +
> > > > +   * **Return fields:**
> > > > +
> > > > +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > > > +         the visible rectangle; it must fit within the frame buffer resolution
> > > > +         returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> > > > +
> > > > +   .. warning::
> > > > +
> > > > +      The decoder may adjust the compose rectangle to the nearest
> > > > +      supported one to meet codec and hardware requirements. The client needs
> > > > +      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
> > > > +
> > > > +6.  If all the following conditions are met, the client may resume the decoding
> > > > +    instantly:
> > > > +
> > > > +    * ``sizeimage`` of the new format (determined in previous steps) is less
> > > > +      than or equal to the size of currently allocated buffers,
> > > > +
> > > > +    * the number of buffers currently allocated is greater than or equal to the
> > > > +      minimum number of buffers acquired in previous steps. To fulfill this
> > > > +      requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
> > > > +      buffers.
> > > > +
> > > > +    In that case, the remaining steps do not apply and the client may resume
> > > > +    the decoding by one of the following actions:
> > > > +
> > > > +    * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
> > > > +      with the ``V4L2_DEC_CMD_START`` command,
> > > > +
> > > > +    * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
> > > > +      on the ``CAPTURE`` queue.
> > > > +
> > > > +    However, if the client intends to change the buffer set, to lower
> > > > +    memory usage or for any other reasons, it may be achieved by following
> > > > +    the steps below.
> > > > +
> > > > +7.  **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
> > > > +    buffers on the ``CAPTURE`` queue until a buffer marked with the
> > > > +    ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
> > > > +
> > > > +8.  **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
> > > > +    on the ``CAPTURE`` queue to stop streaming.
> > > > +
> > > > +    .. warning::
> > > > +
> > > > +       The ``OUTPUT`` queue must remain streaming. Calling
> > > > +       :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
> > > > +       seek.
> > > > +
> > > > +9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
> > > > +    buffers using :c:func:`VIDIOC_REQBUFS`.
> > > > +
> > > > +    * **Required fields:**
> > > > +
> > > > +      ``count``
> > > > +          set to 0.
> > > > +
> > > > +      ``type``
> > > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > > +
> > > > +      ``memory``
> > > > +          follows standard semantics.
> > > > +
> > > > +10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
> > > > +    ``CAPTURE`` queue.
> > > > +
> > > > +    * **Required fields:**
> > > > +
> > > > +      ``count``
> > > > +          requested number of buffers to allocate; greater than zero.
> > > > +
> > > > +      ``type``
> > > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > > +
> > > > +      ``memory``
> > > > +          follows standard semantics.
> > > > +
> > > > +    * **Return fields:**
> > > > +
> > > > +      ``count``
> > > > +          actual number of buffers allocated.
> > > > +
> > > > +    .. warning::
> > > > +
> > > > +       The actual number of allocated buffers may differ from the ``count``
> > > > +       given. The client must check the updated value of ``count`` after the
> > > > +       call returns.
> > > > +
> > > > +    .. note::
> > > > +
> > > > +       To allocate more than the minimum number of buffers (for pipeline
> > > > +       depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
> > > > +       control to get the minimum number of buffers required, and pass the
> > > > +       obtained value plus the number of additional buffers needed in the
> > > > +       ``count`` field to :c:func:`VIDIOC_REQBUFS`.
> > > > +
> > > > +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
> > > > +    used to have more control over buffer allocation. For example, by
> > > > +    allocating buffers larger than the current ``CAPTURE`` format, future
> > > > +    resolution changes can be accommodated.
> > > > +
> > > > +    * **Required fields:**
> > > > +
> > > > +      ``count``
> > > > +          requested number of buffers to allocate; greater than zero.
> > > > +
> > > > +      ``type``
> > > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > > +
> > > > +      ``memory``
> > > > +          follows standard semantics.
> > > > +
> > > > +      ``format``
> > > > +          a format representing the maximum framebuffer resolution to be
> > > > +          accommodated by newly allocated buffers.
> > > > +
> > > > +    * **Return fields:**
> > > > +
> > > > +      ``count``
> > > > +          adjusted to the number of allocated buffers.
> > > > +
> > > > +    .. warning::
> > > > +
> > > > +        The actual number of allocated buffers may differ from the ``count``
> > > > +        given. The client must check the updated value of ``count`` after the
> > > > +        call returns.
> > > > +
> > > > +    .. note::
> > > > +
> > > > +       To allocate buffers for a format different than parsed from the stream
> > > > +       metadata, the client must proceed as follows, before the metadata
> > > > +       parsing is initiated:
> > > > +
> > > > +       * set width and height of the ``OUTPUT`` format to desired coded resolution to
> > > > +         let the decoder configure the ``CAPTURE`` format appropriately,
> > > > +
> > > > +       * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
> > > > +         until this step.
> > > > +
> > > > +       The format obtained in the query may be then used with
> > > > +       :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
> > > > +
> > > > +11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
> > > > +    frames.
> > > > +
> > > > +Decoding
> > > > +========
> > > > +
> > > > +This state is reached after the `Capture setup` sequence finishes successfully.
> > > > +In this state, the client queues and dequeues buffers to both queues via
> > > > +:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
> > > > +semantics.
> > > > +
> > > > +The content of the source ``OUTPUT`` buffers depends on the active coded pixel
> > > > +format and may be affected by codec-specific extended controls, as stated in
> > > > +the documentation of each format.
> > > > +
> > > > +Both queues operate independently, following the standard behavior of V4L2
> > > > +buffer queues and memory-to-memory devices. In addition, the order of decoded
> > > > +frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
> > > > +coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
> > > > +format, e.g. frame reordering.
> > > > +
> > > > +The client must not assume any direct relationship between ``CAPTURE``
> > > > +and ``OUTPUT`` buffers and any specific timing of buffers becoming
> > > > +available to dequeue. Specifically:
> > > > +
> > > > +* a buffer queued to ``OUTPUT`` may result in no buffers being produced
> > > > +  on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
> > > > +  metadata syntax structures are present in it),
> > > > +
> > > > +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
> > > > +  on ``CAPTURE`` (if the encoded data contained more than one frame, or if
> > > > +  returning a decoded frame allowed the decoder to return a frame that
> > > > +  preceded it in decode, but succeeded it in the display order),
> > > > +
> > > > +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
> > > > +  ``CAPTURE`` later into decode process, and/or after processing further
> > > > +  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
> > > > +  reordering is used,
> > > > +
> > > > +* buffers may become available on the ``CAPTURE`` queue without additional
> > > > +  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
> > > > +  ``OUTPUT`` buffers queued in the past whose decoding results are only
> > > > +  available at later time, due to specifics of the decoding process.
> > > > +
> > > > +.. note::
> > > > +
> > > > +   To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
> > > > +   originated from, the client can set the ``timestamp`` field of the
> > > > +   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
> > > > +   ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
> > > > +   will have their ``timestamp`` field set to the same value when dequeued.
> > > > +
> > > > +   In addition to the straightforward case of one ``OUTPUT`` buffer producing
> > > > +   one ``CAPTURE`` buffer, the following cases are defined:
> > > > +
> > > > +   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
> > > > +     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
> > > > +
> > > > +   * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
> > > > +     the ``OUTPUT`` buffer queued last will be copied.
> > > > +
> > > > +   * the decoding order differs from the display order (i.e. the ``CAPTURE``
> > > > +     buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
> > > > +     timestamps will not retain the order of ``OUTPUT`` timestamps.
> > > > +
> > > > +During the decoding, the decoder may initiate one of the special sequences, as
> > > > +listed below. The sequences will result in the decoder returning all the
> > > > +``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
> > > > +before the sequence started. Last of the buffers will have the
> > > > +``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
> > > > +must check if there is any pending event and:
> > > > +
> > > > +* if a ``V4L2_EVENT_SOURCE_CHANGE`` event is pending, the `Dynamic resolution
> > > > +  change` sequence needs to be followed,
> > > > +
> > > > +* if a ``V4L2_EVENT_EOS`` event is pending, the `End of stream` sequence needs
> > > > +  to be followed.
> > > > +
> > > > +Some of the sequences can be intermixed with each other and need to be handled
> > > > +as they happen. The exact operation is documented for each sequence.
> > > > +
> > > > +Should a decoding error occur, it will be reported to the client with the level
> > > > +of details depending on the decoder capabilities. Specifically:
> > > > +
> > > > +* the CAPTURE buffer that contains the results of the failed decode operation
> > > > +  will be returned with the V4L2_BUF_FLAG_ERROR flag set,
> > > > +
> > > > +* if the decoder is able to precisely report the OUTPUT buffer that triggered
> > > > +  the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
> > > > +  set.
> > > > +
> > > > +In case of a fatal failure that does not allow the decoding to continue, any
> > > > +further operations on corresponding decoder file handle will return the -EIO
> > > > +error code. The client may close the file handle and open a new one, or
> > > > +alternatively reinitialize the instance by stopping streaming on both queues,
> > > > +releasing all buffers and performing the Initialization sequence again.
> > > > +
> > > > +Seek
> > > > +====
> > > > +
> > > > +Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
> > > > +The seek does not require any specific operation on the ``CAPTURE`` queue, but
> > > > +it may be affected as per normal decoder operation.
> > > > +
> > > > +1. Stop the ``OUTPUT`` queue to begin the seek sequence via
> > > > +   :c:func:`VIDIOC_STREAMOFF`.
> > > > +
> > > > +   * **Required fields:**
> > > > +
> > > > +     ``type``
> > > > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > > +
> > > > +   * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
> > > > +     treated as returned to the client (following standard semantics).
> > > > +
> > > > +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`
> > > > +
> > > > +   * **Required fields:**
> > > > +
> > > > +     ``type``
> > > > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > > +
> > > > +   * The decoder will start accepting new source bitstream buffers after the
> > > > +     call returns.
> > > > +
> > > > +3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
> > > > +   queue until a suitable resume point is found.
> > > > +
> > > > +   .. note::
> > > > +
> > > > +      There is no requirement to begin queuing coded data starting exactly
> > > > +      from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
> > > > +      buffers will be processed and returned to the client until a suitable
> > > > +      resume point is found.  While looking for a resume point, the decoder
> > > > +      should not produce any decoded frames into ``CAPTURE`` buffers.
> > > > +
> > > > +      Some hardware is known to mishandle seeks to a non-resume point. Such an
> > > > +      operation may result in an unspecified number of corrupted decoded frames
> > > > +      being made available on the ``CAPTURE`` queue. Drivers must ensure that
> > > > +      no fatal decoding errors or crashes occur, and implement any necessary
> > > > +      handling and workarounds for hardware issues related to seek operations.
> > > > +
> > > > +   .. warning::
> > > > +
> > > > +      In case of the H.264/HEVC codec, the client must take care not to seek
> > > > +      over a change of SPS/PPS. Even though the target frame could be a
> > > > +      keyframe, the stale SPS/PPS inside decoder state would lead to undefined
> > > > +      results when decoding. Although the decoder must handle that case without
> > > > +      a crash or a fatal decode error, the client must not expect a sensible
> > > > +      decode output.
> > > > +
> > > > +      If the hardware can detect such corrupted decoded frames, then
> > > > +      corresponding buffers will be returned to the client with the
> > > > +      V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
> > > > +      description of decode error reporting.
> > > > +
> > > > +4. After a resume point is found, the decoder will start returning ``CAPTURE``
> > > > +   buffers containing decoded frames.
> > > > +
> > > > +.. important::
> > > > +
> > > > +   A seek may result in the `Dynamic resolution change` sequence being
> > > > +   initiated, due to the seek target having decoding parameters different from
> > > > +   the part of the stream decoded before the seek. The sequence must be handled
> > > > +   as per normal decoder operation.
> > > > +
> > > > +.. warning::
> > > > +
> > > > +   It is not specified when the ``CAPTURE`` queue starts producing buffers
> > > > +   containing decoded data from the ``OUTPUT`` buffers queued after the seek,
> > > > +   as it operates independently from the ``OUTPUT`` queue.
> > > > +
> > > > +   The decoder may return a number of remaining ``CAPTURE`` buffers containing
> > > > +   decoded frames originating from the ``OUTPUT`` buffers queued before the
> > > > +   seek sequence is performed.
> > > > +
> > > > +   The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
> > > > +   ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
> > > > +   queued before the seek sequence may have matching ``CAPTURE`` buffers
> > > > +   produced.  For example, given the sequence of operations on the
> > > > +   ``OUTPUT`` queue:
> > > > +
> > > > +     QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
> > > > +
> > > > +   any of the following results on the ``CAPTURE`` queue is allowed:
> > > > +
> > > > +     {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}.
> > > > +
> > > > +   To determine the CAPTURE buffer containing the first decoded frame after the
> > > > +   seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
> > > > +   buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
> > > > +   decoder.
> > > > +
> > > > +.. note::
> > > > +
> > > > +   To achieve instantaneous seek, the client may restart streaming on the
> > > > +   ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
> > > > +
> > > > +Dynamic resolution change
> > > > +=========================
> > > > +
> > > > +Streams that include resolution metadata in the bitstream may require switching
> > > > +to a different resolution during the decoding.
> > > > +
> > > > +The sequence starts when the decoder detects a coded frame with one or more of
> > > > +the following parameters different from those previously established (and
> > > > +reflected by corresponding queries):
> > > > +
> > > > +* coded resolution (``OUTPUT`` width and height),
> > > > +
> > > > +* visible resolution (selection rectangles),
> > > > +
> > > > +* the minimum number of buffers needed for decoding.
> > > > +
> > > > +Whenever that happens, the decoder must proceed as follows:
> > > > +
> > > > +1.  After encountering a resolution change in the stream, the decoder sends a
> > > > +    ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
> > > > +    ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> > > 
> > > What about a format changes that does now affect the resolution, like a
> > > pixel format change ? Also, what about changes that don't require a
> > 
> > A pixel format change always implies a resolution change.
> > 
> > > reallocation ? Like a change in the colorimetry parameters ? I don't
> > > think the spec need to initially cover it all, but we need to make sure
> > > there is a mechanism for userspace to know at which frames to read back
> > > the new format (G_FMT). Maybe we need both an event and a buffer flag
> > > to mark it ?
> > 
> > After a SOURCE_CHANGE event is received, G_FMT returns the *new* format,
> > including colorimetry. This will become the active format once the drain
> > operation finished.
> > 
> > If that's not clear from the spec, then I need to improve it.
> > 
> > Regards,
> > 
> >         Hans
> > 
> > > > +
> > > > +    .. important::
> > > > +
> > > > +       Any client query issued after the decoder queues the event will return
> > > > +       values applying to the stream after the resolution change, including
> > > > +       queue formats, selection rectangles and controls.
> > > > +
> > > > +2.  The decoder will then process and decode all remaining buffers from before
> > > > +    the resolution change point.
> > > > +
> > > > +    * The last buffer from before the change must be marked with the
> > > > +      ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
> > > > +
> > > > +    .. warning::
> > > > +
> > > > +       The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
> > > > +       = 0) and in that case it must be ignored by the client, as it does not
> > > > +       contain a decoded frame.
> > > > +
> > > > +    .. note::
> > > > +
> > > > +       Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
> > > > +       with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
> > > > +       :c:func:`VIDIOC_DQBUF`.
> > > > +
> > > > +The client must continue the sequence as described below to continue the
> > > > +decoding process.
> > > > +
> > > > +1.  Dequeue the source change event.
> > > > +
> > > > +    .. important::
> > > > +
> > > > +       A source change triggers an implicit decoder drain, similar to the
> > > > +       explicit `Drain` sequence. The decoder is stopped after it completes.
> > > > +       The decoding process must be resumed with either a pair of calls to
> > > > +       :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> > > > +       ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
> > > > +       ``V4L2_DEC_CMD_START`` command.
> > > > +
> > > > +2.  Continue with the `Capture setup` sequence.
> > > > +
> > > > +.. note::
> > > > +
> > > > +   During the resolution change sequence, the ``OUTPUT`` queue must remain
> > > > +   streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
> > > > +   abort the sequence and initiate a seek.
> > > > +
> > > > +   In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
> > > > +   queue and this remains true for the duration of the entire resolution change
> > > > +   sequence as well.
> > > > +
> > > > +   The client should, for best performance and simplicity, keep queuing/dequeuing
> > > > +   buffers to/from the ``OUTPUT`` queue even while processing this sequence.
> > > > +
> > > > +Drain
> > > > +=====
> > > > +
> > > > +To ensure that all queued ``OUTPUT`` buffers have been processed and related
> > > > +``CAPTURE`` buffers are given to the client, the client must follow the drain
> > > > +sequence described below. After the drain sequence ends, the client has
> > > > +received all decoded frames for all ``OUTPUT`` buffers queued before the
> > > > +sequence was started.
> > > > +
> > > > +1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
> > > > +
> > > > +   * **Required fields:**
> > > > +
> > > > +     ``cmd``
> > > > +         set to ``V4L2_DEC_CMD_STOP``.
> > > > +
> > > > +     ``flags``
> > > > +         set to 0.
> > > > +
> > > > +     ``pts``
> > > > +         set to 0.
> > > > +
> > > > +   .. warning::
> > > > +
> > > > +      The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
> > > > +      queues are streaming. For compatibility reasons, the call to
> > > > +      :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
> > > > +      not streaming, but at the same time it will not initiate the `Drain`
> > > > +      sequence and so the steps described below would not be applicable.
> > > > +
> > > > +2. Any ``OUTPUT`` buffers queued by the client before the
> > > > +   :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
> > > > +   normal. The client must continue to handle both queues independently,
> > > > +   similarly to normal decode operation. This includes:
> > > > +
> > > > +   * handling any operations triggered as a result of processing those buffers,
> > > > +     such as the `Dynamic resolution change` sequence, before continuing with
> > > > +     the drain sequence,
> > > > +
> > > > +   * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
> > > > +     ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
> > > > +
> > > > +     .. warning::
> > > > +
> > > > +        The last buffer may be empty (with :c:type:`v4l2_buffer`
> > > > +        ``bytesused`` = 0) and in that case it must be ignored by the client,
> > > > +        as it does not contain a decoded frame.
> > > > +
> > > > +     .. note::
> > > > +
> > > > +        Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
> > > > +        marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
> > > > +        :c:func:`VIDIOC_DQBUF`.
> > > > +
> > > > +   * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
> > > > +     before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
> > > > +
> > > > +   * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
> > > > +
> > > > +   .. note::
> > > > +
> > > > +      For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
> > > > +      event when the last frame has been decoded and all frames are ready to be
> > > > +      dequeued. It is a deprecated behavior and the client must not rely on it.
> > > > +      The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
> > > > +
> > > > +3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
> > > > +   are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
> > > > +   stopped and it will accept, but not process, any newly queued ``OUTPUT``
> > > > +   buffers until the client issues any of the following operations:
> > > > +
> > > > +   * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
> > > > +     operation normally, with all the state from before the drain,
> > > > +
> > > > +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> > > > +     ``CAPTURE`` queue - the decoder will resume the operation normally,
> > > > +     however any ``CAPTURE`` buffers still in the queue will be returned to the
> > > > +     client,
> > > > +
> > > > +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> > > > +     ``OUTPUT`` queue - any pending source buffers will be returned to the
> > > > +     client and the `Seek` sequence will be triggered.
> > > > +
> > > > +.. note::
> > > > +
> > > > +   Once the drain sequence is initiated, the client needs to drive it to
> > > > +   completion, as described by the steps above, unless it aborts the process by
> > > > +   issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
> > > > +   queues.  The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
> > > > +   ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
> > > > +   will fail with -EBUSY error code if attempted.
> > > > +
> > > > +   Although mandatory, the availability of decoder commands may be queried
> > > > +   using :c:func:`VIDIOC_TRY_DECODER_CMD`.
> > > > +
> > > > +End of stream
> > > > +=============
> > > > +
> > > > +If the decoder encounters an end of stream marking in the stream, the decoder
> > > > +will initiate the `Drain` sequence, which the client must handle as described
> > > > +above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
> > > > +
> > > > +Commit points
> > > > +=============
> > > > +
> > > > +Setting formats and allocating buffers trigger changes in the behavior of the
> > > > +decoder.
> > > > +
> > > > +1. Setting the format on the ``OUTPUT`` queue may change the set of formats
> > > > +   supported/advertised on the ``CAPTURE`` queue. In particular, it also means
> > > > +   that the ``CAPTURE`` format may be reset and the client must not rely on the
> > > > +   previously set format being preserved.
> > > > +
> > > > +2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
> > > > +   supported for the current ``OUTPUT`` format.
> > > > +
> > > > +3. Setting the format on the ``CAPTURE`` queue does not change the list of
> > > > +   formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
> > > > +   format that is not supported for the currently selected ``OUTPUT`` format
> > > > +   will result in the decoder adjusting the requested ``CAPTURE`` format to a
> > > > +   supported one.
> > > > +
> > > > +4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
> > > > +   supported coded formats, irrespectively of the current ``CAPTURE`` format.
> > > > +
> > > > +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
> > > > +   the client must not change the format on the ``OUTPUT`` queue. Drivers will
> > > > +   return the -EBUSY error code for any such format change attempt.
> > > > +
> > > > +To summarize, setting formats and allocation must always start with the
> > > > +``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
> > > > +set of supported formats for the ``CAPTURE`` queue.
> > > > diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> > > > index 67a980818dc8..caa05f5f6380 100644
> > > > --- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
> > > > +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> > > > @@ -39,4 +39,10 @@ file handle is visible through another file handle).
> > > >  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
> > > > diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> > > > index 71eebfc6d853..caf14e440447 100644
> > > > --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> > > > +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> > > > @@ -39,6 +39,11 @@ Single-planar format structure
> > > >      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.
> > > > diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> > > > index 004ec00db6bd..97015b9b40b8 100644
> > > > --- a/Documentation/media/uapi/v4l/v4l2.rst
> > > > +++ b/Documentation/media/uapi/v4l/v4l2.rst
> > > > @@ -60,6 +60,10 @@ Authors, in alphabetical order:
> > > > 
> > > >    - 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.
> > > > @@ -68,6 +72,10 @@ Authors, in alphabetical order:
> > > > 
> > > >    - 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.
> > > > @@ -92,7 +100,7 @@ Authors, in alphabetical order:
> > > > 
> > > >    - 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.
> > > > diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> > > > index ccf83b05afa7..57f0066f4cff 100644
> > > > --- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> > > > +++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> > > > @@ -56,14 +56,16 @@ The ``cmd`` field must contain the command code. Some commands use the
> > > > 
> > > >  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}|
> > > > @@ -167,26 +169,32 @@ introduced in Linux 3.3.
> > > >      ``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
> > > > @@ -209,6 +217,11 @@ 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.
> > > > 
> > > > +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.
> > > > 

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Tomasz Figa]

Hi Hans,

On Mon, Jun 3, 2019 at 8:28 PM Hans Verkuil <hverkuil-cisco@xs4all.nl> wrote:
>
> From: Tomasz Figa <tfiga@chromium.org>
>
> Due to complexity of the video decoding process, the V4L2 drivers of
> stateful decoder hardware require specific sequences of V4L2 API calls
> to be followed. These include capability enumeration, initialization,
> decoding, seek, pause, dynamic resolution change, drain and end of
> stream.
>
> Specifics of the above have been discussed during Media Workshops at
> LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
> Conference Europe 2014 in Düsseldorf. The de facto Codec API that
> originated at those events was later implemented by the drivers we already
> have merged in mainline, such as s5p-mfc or coda.
>
> The only thing missing was the real specification included as a part of
> Linux Media documentation. Fix it now and document the decoder part of
> the Codec API.
>
> Signed-off-by: Tomasz Figa <tfiga@chromium.org>
> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> ---
>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
>  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
>  5 files changed, 1132 insertions(+), 16 deletions(-)
>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>

Thanks a lot for helping with remaining changes.

Just one thing inline our team member found recently.

[snip]
> +Capture setup
> +=============
> +
[snip]
> +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
> +    ``CAPTURE`` queue. The client may choose a different format than
> +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
> +
> +    * **Required fields:**
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``pixelformat``
> +          a raw pixel format.

The client should be able to set the width and height as well. It's a
quite frequent case, especially in DMA-buf import mode, that the
buffers are actually bigger (e.g. more alignment) than what we could
get from the decoder by default. For sane hardware platforms it's
reasonable to expect that such bigger buffers could be handled as
well, as long as we update the width and height here.

It's more like a clarification anyway, so if you think it would be
better to just merge the current revision, I could send a follow up
patch.

Regardless of that and FWIW:

Reviewed-by: Tomasz Figa <tfiga@chromium.org>

Best regards,
Tomasz

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Hans Verkuil]

On 7/3/19 6:58 AM, Tomasz Figa wrote:
> Hi Hans,
> 
> On Mon, Jun 3, 2019 at 8:28 PM Hans Verkuil <hverkuil-cisco@xs4all.nl> wrote:
>>
>> From: Tomasz Figa <tfiga@chromium.org>
>>
>> Due to complexity of the video decoding process, the V4L2 drivers of
>> stateful decoder hardware require specific sequences of V4L2 API calls
>> to be followed. These include capability enumeration, initialization,
>> decoding, seek, pause, dynamic resolution change, drain and end of
>> stream.
>>
>> Specifics of the above have been discussed during Media Workshops at
>> LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
>> Conference Europe 2014 in Düsseldorf. The de facto Codec API that
>> originated at those events was later implemented by the drivers we already
>> have merged in mainline, such as s5p-mfc or coda.
>>
>> The only thing missing was the real specification included as a part of
>> Linux Media documentation. Fix it now and document the decoder part of
>> the Codec API.
>>
>> Signed-off-by: Tomasz Figa <tfiga@chromium.org>
>> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
>> ---
>>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
>>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
>>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
>>  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
>>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
>>  5 files changed, 1132 insertions(+), 16 deletions(-)
>>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>>
> 
> Thanks a lot for helping with remaining changes.
> 
> Just one thing inline our team member found recently.
> 
> [snip]
>> +Capture setup
>> +=============
>> +
> [snip]
>> +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
>> +    ``CAPTURE`` queue. The client may choose a different format than
>> +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
>> +
>> +    * **Required fields:**
>> +
>> +      ``type``
>> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
>> +
>> +      ``pixelformat``
>> +          a raw pixel format.
> 
> The client should be able to set the width and height as well. It's a
> quite frequent case, especially in DMA-buf import mode, that the
> buffers are actually bigger (e.g. more alignment) than what we could
> get from the decoder by default. For sane hardware platforms it's
> reasonable to expect that such bigger buffers could be handled as
> well, as long as we update the width and height here.

I've added this:

     ``width``, ``height``
         frame buffer resolution of the decoded stream; typically unchanged from
         what was returned with :c:func:`VIDIOC_G_FMT`, but it may be different
         if the hardware supports composition and/or scaling.

Is that what you were looking for?

> 
> It's more like a clarification anyway, so if you think it would be
> better to just merge the current revision, I could send a follow up
> patch.
> 
> Regardless of that and FWIW:
> 
> Reviewed-by: Tomasz Figa <tfiga@chromium.org>

Thanks!

	Hans

> 
> Best regards,
> Tomasz
> 

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Tomasz Figa]

On Wed, Jul 10, 2019 at 5:09 PM Hans Verkuil <hverkuil-cisco@xs4all.nl> wrote:
>
> On 7/3/19 6:58 AM, Tomasz Figa wrote:
> > Hi Hans,
> >
> > On Mon, Jun 3, 2019 at 8:28 PM Hans Verkuil <hverkuil-cisco@xs4all.nl> wrote:
> >>
> >> From: Tomasz Figa <tfiga@chromium.org>
> >>
> >> Due to complexity of the video decoding process, the V4L2 drivers of
> >> stateful decoder hardware require specific sequences of V4L2 API calls
> >> to be followed. These include capability enumeration, initialization,
> >> decoding, seek, pause, dynamic resolution change, drain and end of
> >> stream.
> >>
> >> Specifics of the above have been discussed during Media Workshops at
> >> LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
> >> Conference Europe 2014 in Düsseldorf. The de facto Codec API that
> >> originated at those events was later implemented by the drivers we already
> >> have merged in mainline, such as s5p-mfc or coda.
> >>
> >> The only thing missing was the real specification included as a part of
> >> Linux Media documentation. Fix it now and document the decoder part of
> >> the Codec API.
> >>
> >> Signed-off-by: Tomasz Figa <tfiga@chromium.org>
> >> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> >> ---
> >>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
> >>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
> >>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
> >>  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
> >>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
> >>  5 files changed, 1132 insertions(+), 16 deletions(-)
> >>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> >>
> >
> > Thanks a lot for helping with remaining changes.
> >
> > Just one thing inline our team member found recently.
> >
> > [snip]
> >> +Capture setup
> >> +=============
> >> +
> > [snip]
> >> +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
> >> +    ``CAPTURE`` queue. The client may choose a different format than
> >> +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
> >> +
> >> +    * **Required fields:**
> >> +
> >> +      ``type``
> >> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> >> +
> >> +      ``pixelformat``
> >> +          a raw pixel format.
> >
> > The client should be able to set the width and height as well. It's a
> > quite frequent case, especially in DMA-buf import mode, that the
> > buffers are actually bigger (e.g. more alignment) than what we could
> > get from the decoder by default. For sane hardware platforms it's
> > reasonable to expect that such bigger buffers could be handled as
> > well, as long as we update the width and height here.
>
> I've added this:
>
>      ``width``, ``height``
>          frame buffer resolution of the decoded stream; typically unchanged from
>          what was returned with :c:func:`VIDIOC_G_FMT`, but it may be different
>          if the hardware supports composition and/or scaling.
>
> Is that what you were looking for?
>

Not sure if composition is a requirement here, but I guess it depends
on how we define composition. Most of the hardware today at least
support arbitrary strides (+/- some alignment), but still write the
pixels at (0,0)x(w,h).

In fact, there would be already some composition happening, even
without arbitrary strides, because G_FMT would return values aligned
in some way, but only the visible rectangle would contain meaningful
pixel data.

Best regards,
Tomasz

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Hans Verkuil]

On 7/10/19 10:23 AM, Tomasz Figa wrote:
> On Wed, Jul 10, 2019 at 5:09 PM Hans Verkuil <hverkuil-cisco@xs4all.nl> wrote:
>>
>> On 7/3/19 6:58 AM, Tomasz Figa wrote:
>>> Hi Hans,
>>>
>>> On Mon, Jun 3, 2019 at 8:28 PM Hans Verkuil <hverkuil-cisco@xs4all.nl> wrote:
>>>>
>>>> From: Tomasz Figa <tfiga@chromium.org>
>>>>
>>>> Due to complexity of the video decoding process, the V4L2 drivers of
>>>> stateful decoder hardware require specific sequences of V4L2 API calls
>>>> to be followed. These include capability enumeration, initialization,
>>>> decoding, seek, pause, dynamic resolution change, drain and end of
>>>> stream.
>>>>
>>>> Specifics of the above have been discussed during Media Workshops at
>>>> LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
>>>> Conference Europe 2014 in Düsseldorf. The de facto Codec API that
>>>> originated at those events was later implemented by the drivers we already
>>>> have merged in mainline, such as s5p-mfc or coda.
>>>>
>>>> The only thing missing was the real specification included as a part of
>>>> Linux Media documentation. Fix it now and document the decoder part of
>>>> the Codec API.
>>>>
>>>> Signed-off-by: Tomasz Figa <tfiga@chromium.org>
>>>> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
>>>> ---
>>>>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
>>>>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
>>>>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
>>>>  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
>>>>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
>>>>  5 files changed, 1132 insertions(+), 16 deletions(-)
>>>>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>>>>
>>>
>>> Thanks a lot for helping with remaining changes.
>>>
>>> Just one thing inline our team member found recently.
>>>
>>> [snip]
>>>> +Capture setup
>>>> +=============
>>>> +
>>> [snip]
>>>> +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
>>>> +    ``CAPTURE`` queue. The client may choose a different format than
>>>> +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
>>>> +
>>>> +    * **Required fields:**
>>>> +
>>>> +      ``type``
>>>> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
>>>> +
>>>> +      ``pixelformat``
>>>> +          a raw pixel format.
>>>
>>> The client should be able to set the width and height as well. It's a
>>> quite frequent case, especially in DMA-buf import mode, that the
>>> buffers are actually bigger (e.g. more alignment) than what we could
>>> get from the decoder by default. For sane hardware platforms it's
>>> reasonable to expect that such bigger buffers could be handled as
>>> well, as long as we update the width and height here.
>>
>> I've added this:
>>
>>      ``width``, ``height``
>>          frame buffer resolution of the decoded stream; typically unchanged from
>>          what was returned with :c:func:`VIDIOC_G_FMT`, but it may be different
>>          if the hardware supports composition and/or scaling.
>>
>> Is that what you were looking for?
>>
> 
> Not sure if composition is a requirement here, but I guess it depends
> on how we define composition. Most of the hardware today at least
> support arbitrary strides (+/- some alignment), but still write the
> pixels at (0,0)x(w,h).
> 
> In fact, there would be already some composition happening, even
> without arbitrary strides, because G_FMT would return values aligned
> in some way, but only the visible rectangle would contain meaningful
> pixel data.

Pretty much all codec drivers can handle composition, and with that I
don't mean the macroblock alignment, but that it can compose in, say,
a buffer that's twice the width/height than is strictly required.

And yes, it is a limited form of composition in that the top left corner
typically can't be changed.

Regards,

	Hans

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Nicolas Dufresne]

[-- Attachment #1: Type: text/plain, Size: 57154 bytes --]

Hello,

there is one little detail/proposal, see inline	.

Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> From: Tomasz Figa <tfiga@chromium.org>
> 
> Due to complexity of the video decoding process, the V4L2 drivers of
> stateful decoder hardware require specific sequences of V4L2 API calls
> to be followed. These include capability enumeration, initialization,
> decoding, seek, pause, dynamic resolution change, drain and end of
> stream.
> 
> Specifics of the above have been discussed during Media Workshops at
> LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
> Conference Europe 2014 in Düsseldorf. The de facto Codec API that
> originated at those events was later implemented by the drivers we already
> have merged in mainline, such as s5p-mfc or coda.
> 
> The only thing missing was the real specification included as a part of
> Linux Media documentation. Fix it now and document the decoder part of
> the Codec API.
> 
> Signed-off-by: Tomasz Figa <tfiga@chromium.org>
> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> ---
>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
>  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
>  5 files changed, 1132 insertions(+), 16 deletions(-)
>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> 
> diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst
> new file mode 100644
> index 000000000000..b106f2d97c48
> --- /dev/null
> +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
> @@ -0,0 +1,1084 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _decoder:
> +
> +*************************************************
> +Memory-to-memory Stateful Video Decoder Interface
> +*************************************************
> +
> +A stateful video decoder takes complete chunks of the bitstream (e.g. Annex-B
> +H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
> +display order. The decoder is expected not to require any additional information
> +from the client to process these buffers.
> +
> +Performing software parsing, processing etc. of the stream in the driver in
> +order to support this interface is strongly discouraged. In case such
> +operations are needed, use of the Stateless Video Decoder Interface (in
> +development) is strongly advised.
> +
> +Conventions and notation used in this document
> +==============================================
> +
> +1. The general V4L2 API rules apply if not specified in this document
> +   otherwise.
> +
> +2. The meaning of words "must", "may", "should", etc. is as per `RFC
> +   2119 <https://tools.ietf.org/html/rfc2119>`_.
> +
> +3. All steps not marked "optional" are required.
> +
> +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
> +   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
> +   unless specified otherwise.
> +
> +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
> +   used interchangeably with multi-planar API, unless specified otherwise,
> +   depending on decoder capabilities and following the general V4L2 guidelines.
> +
> +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
> +   [0..2]: i = 0, 1, 2.
> +
> +7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
> +   queue containing data that resulted from processing buffer A.
> +
> +.. _decoder-glossary:
> +
> +Glossary
> +========
> +
> +CAPTURE
> +   the destination buffer queue; for decoders, the queue of buffers containing
> +   decoded frames; for encoders, the queue of buffers containing an encoded
> +   bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
> +   ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
> +   into ``CAPTURE`` buffers.
> +
> +client
> +   the application communicating with the decoder or encoder implementing
> +   this interface.
> +
> +coded format
> +   encoded/compressed video bitstream format (e.g. H.264, VP8, etc.); see
> +   also: raw format.
> +
> +coded height
> +   height for given coded resolution.
> +
> +coded resolution
> +   stream resolution in pixels aligned to codec and hardware requirements;
> +   typically visible resolution rounded up to full macroblocks;
> +   see also: visible resolution.
> +
> +coded width
> +   width for given coded resolution.
> +
> +decode order
> +   the order in which frames are decoded; may differ from display order if the
> +   coded format includes a feature of frame reordering; for decoders,
> +   ``OUTPUT`` buffers must be queued by the client in decode order; for
> +   encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
> +
> +destination
> +   data resulting from the decode process; see ``CAPTURE``.
> +
> +display order
> +   the order in which frames must be displayed; for encoders, ``OUTPUT``
> +   buffers must be queued by the client in display order; for decoders,
> +   ``CAPTURE`` buffers must be returned by the decoder in display order.
> +
> +DPB
> +   Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
> +   raw frame available for reference in further decoding steps.
> +
> +EOS
> +   end of stream.
> +
> +IDR
> +   Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
> +   stream, which clears the list of earlier reference frames (DPBs).
> +
> +keyframe
> +   an encoded frame that does not reference frames decoded earlier, i.e.
> +   can be decoded fully on its own.
> +
> +macroblock
> +   a processing unit in image and video compression formats based on linear
> +   block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
> +   popular codecs the size is 16x16 samples (pixels).
> +
> +OUTPUT
> +   the source buffer queue; for decoders, the queue of buffers containing
> +   an encoded bitstream; for encoders, the queue of buffers containing raw
> +   frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
> +   ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
> +   from ``OUTPUT`` buffers.
> +
> +PPS
> +   Picture Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> +
> +raw format
> +   uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
> +
> +resume point
> +   a point in the bitstream from which decoding may start/continue, without
> +   any previous state/data present, e.g.: a keyframe (VP8/VP9) or
> +   SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
> +   of a new stream, or to resume decoding after a seek.
> +
> +source
> +   data fed to the decoder or encoder; see ``OUTPUT``.
> +
> +source height
> +   height in pixels for given source resolution; relevant to encoders only.
> +
> +source resolution
> +   resolution in pixels of source frames being source to the encoder and
> +   subject to further cropping to the bounds of visible resolution; relevant to
> +   encoders only.
> +
> +source width
> +   width in pixels for given source resolution; relevant to encoders only.
> +
> +SPS
> +   Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> +
> +stream metadata
> +   additional (non-visual) information contained inside encoded bitstream;
> +   for example: coded resolution, visible resolution, codec profile.
> +
> +visible height
> +   height for given visible resolution; display height.
> +
> +visible resolution
> +   stream resolution of the visible picture, in pixels, to be used for
> +   display purposes; must be smaller or equal to coded resolution;
> +   display resolution.
> +
> +visible width
> +   width for given visible resolution; display width.
> +
> +State machine
> +=============
> +
> +.. kernel-render:: DOT
> +   :alt: DOT digraph of decoder state machine
> +   :caption: Decoder state machine
> +
> +   digraph decoder_state_machine {
> +       node [shape = doublecircle, label="Decoding"] Decoding;
> +
> +       node [shape = circle, label="Initialization"] Initialization;
> +       node [shape = circle, label="Capture\nsetup"] CaptureSetup;
> +       node [shape = circle, label="Dynamic\nresolution\nchange"] ResChange;
> +       node [shape = circle, label="Stopped"] Stopped;
> +       node [shape = circle, label="Drain"] Drain;
> +       node [shape = circle, label="Seek"] Seek;
> +       node [shape = circle, label="End of stream"] EoS;
> +
> +       node [shape = point]; qi
> +       qi -> Initialization [ label = "open()" ];
> +
> +       Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> +
> +       CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
> +
> +       Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
> +       Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
> +       Decoding -> EoS [ label = "EoS mark\nin the stream" ];
> +       Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> +       Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
> +       Decoding -> Decoding;
> +
> +       ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> +       ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> +
> +       EoS -> Drain [ label = "Implicit\ndrain" ];
> +
> +       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
> +       Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> +
> +       Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
> +       Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
> +
> +       Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
> +       Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> +   }
> +
> +Querying capabilities
> +=====================
> +
> +1. To enumerate the set of coded formats supported by the decoder, the
> +   client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
> +
> +   * The full set of supported formats will be returned, regardless of the
> +     format set on ``CAPTURE``.
> +
> +2. To enumerate the set of supported raw formats, the client may call
> +   :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
> +
> +   * Only the formats supported for the format currently active on ``OUTPUT``
> +     will be returned.
> +
> +   * In order to enumerate raw formats supported by a given coded format,
> +     the client must first set that coded format on ``OUTPUT`` and then
> +     enumerate formats on ``CAPTURE``.
> +
> +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
> +   resolutions for a given format, passing desired pixel format in
> +   :c:type:`v4l2_frmsizeenum` ``pixel_format``.
> +
> +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
> +     format will include all possible coded resolutions supported by the
> +     decoder for given coded pixel format.
> +
> +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
> +     will include all possible frame buffer resolutions supported by the
> +     decoder for given raw pixel format and the coded format currently set on
> +     ``OUTPUT``.
> +
> +4. Supported profiles and levels for the coded format currently set on
> +   ``OUTPUT``, if applicable, may be queried using their respective controls
> +   via :c:func:`VIDIOC_QUERYCTRL`.
> +
> +Initialization
> +==============
> +
> +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
> +
> +   * **Required fields:**
> +
> +     ``type``
> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> +
> +     ``pixelformat``
> +         a coded pixel format.
> +
> +     ``width``, ``height``
> +         coded resolution of the stream; required only if it cannot be parsed
> +         from the stream for the given coded format; otherwise the decoder will
> +         use this resolution as a placeholder resolution that will likely change
> +         as soon as it can parse the actual coded resolution from the stream.
> +
> +     ``sizeimage``
> +         desired size of ``OUTPUT`` buffers; the decoder may adjust it to
> +         match hardware requirements.
> +
> +     other fields
> +         follow standard semantics.
> +
> +   * **Return fields:**
> +
> +     ``sizeimage``
> +         adjusted size of ``OUTPUT`` buffers.
> +
> +   * The ``CAPTURE`` format will be updated with an appropriate frame buffer
> +     resolution instantly based on the width and height returned by
> +     :c:func:`VIDIOC_S_FMT`.
> +     However, for coded formats that include stream resolution information,
> +     after the decoder is done parsing the information from the stream, it will
> +     update the ``CAPTURE`` format with new values and signal a source change
> +     event, regardless of whether they match the values set by the client or
> +     not.
> +
> +   .. important::
> +
> +      Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
> +      format. How the new ``CAPTURE`` format is determined is up to the decoder
> +      and the client must ensure it matches its needs afterwards.
> +
> +2.  Allocate source (bitstream) buffers via :c:func:`VIDIOC_REQBUFS` on
> +    ``OUTPUT``.
> +
> +    * **Required fields:**
> +
> +      ``count``
> +          requested number of buffers to allocate; greater than zero.
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> +
> +      ``memory``
> +          follows standard semantics.
> +
> +    * **Return fields:**
> +
> +      ``count``
> +          the actual number of buffers allocated.
> +
> +    .. warning::
> +
> +       The actual number of allocated buffers may differ from the ``count``
> +       given. The client must check the updated value of ``count`` after the
> +       call returns.
> +
> +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
> +    used to have more control over buffer allocation.
> +
> +    * **Required fields:**
> +
> +      ``count``
> +          requested number of buffers to allocate; greater than zero.
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> +
> +      ``memory``
> +          follows standard semantics.
> +
> +      ``format``
> +          follows standard semantics.
> +
> +    * **Return fields:**
> +
> +      ``count``
> +          adjusted to the number of allocated buffers.
> +
> +    .. warning::
> +
> +       The actual number of allocated buffers may differ from the ``count``
> +       given. The client must check the updated value of ``count`` after the
> +       call returns.
> +
> +3.  Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
> +
> +4.  **This step only applies to coded formats that contain resolution information
> +    in the stream.** Continue queuing/dequeuing bitstream buffers to/from the
> +    ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
> +    buffers will be processed and returned to the client in order, until
> +    required metadata to configure the ``CAPTURE`` queue are found. This is
> +    indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
> +    ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> +
> +    * It is not an error if the first buffer does not contain enough data for
> +      this to occur. Processing of the buffers will continue as long as more
> +      data is needed.
> +
> +    * If data in a buffer that triggers the event is required to decode the
> +      first frame, it will not be returned to the client, until the
> +      initialization sequence completes and the frame is decoded.
> +
> +    * If the client has not set the coded resolution of the stream on its own,
> +      calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
> +      :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
> +      queue will not return the real values for the stream until a
> +      ``V4L2_EVENT_SOURCE_CHANGE`` event is signaled.
> +
> +    .. important::
> +
> +       Any client query issued after the decoder queues the event will return
> +       values applying to the just parsed stream, including queue formats,
> +       selection rectangles and controls.
> +
> +    .. note::
> +
> +       A client capable of acquiring stream parameters from the bitstream on
> +       its own may attempt to set the width and height of the ``OUTPUT`` format
> +       to non-zero values matching the coded size of the stream, skip this step
> +       and continue with the `Capture setup` sequence. However, it must not
> +       rely on any driver queries regarding stream parameters, such as
> +       selection rectangles and controls, since the decoder has not parsed them
> +       from the stream yet. If the values configured by the client do not match
> +       those parsed by the decoder, a `Dynamic resolution change` will be
> +       triggered to reconfigure them.
> +
> +    .. note::
> +
> +       No decoded frames are produced during this phase.
> +
> +5.  Continue with the `Capture setup` sequence.
> +
> +Capture setup
> +=============
> +
> +1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
> +    destination buffers parsed/decoded from the bitstream.
> +
> +    * **Required fields:**
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +    * **Return fields:**
> +
> +      ``width``, ``height``
> +          frame buffer resolution for the decoded frames.
> +
> +      ``pixelformat``
> +          pixel format for decoded frames.
> +
> +      ``num_planes`` (for _MPLANE ``type`` only)
> +          number of planes for pixelformat.
> +
> +      ``sizeimage``, ``bytesperline``
> +          as per standard semantics; matching frame buffer format.
> +
> +    .. note::
> +
> +       The value of ``pixelformat`` may be any pixel format supported by the
> +       decoder for the current stream. The decoder should choose a
> +       preferred/optimal format for the default configuration. For example, a
> +       YUV format may be preferred over an RGB format if an additional
> +       conversion step would be required for the latter.
> +
> +2.  **Optional.** Acquire the visible resolution via
> +    :c:func:`VIDIOC_G_SELECTION`.
> +
> +    * **Required fields:**
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``target``
> +          set to ``V4L2_SEL_TGT_COMPOSE``.
> +
> +    * **Return fields:**
> +
> +      ``r.left``, ``r.top``, ``r.width``, ``r.height``
> +          the visible rectangle; it must fit within the frame buffer resolution
> +          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> +
> +    * The following selection targets are supported on ``CAPTURE``:
> +
> +      ``V4L2_SEL_TGT_CROP_BOUNDS``
> +          corresponds to the coded resolution of the stream.
> +
> +      ``V4L2_SEL_TGT_CROP_DEFAULT``
> +          the rectangle covering the part of the ``CAPTURE`` buffer that
> +          contains meaningful picture data (visible area); width and height
> +          will be equal to the visible resolution of the stream.
> +
> +      ``V4L2_SEL_TGT_CROP``
> +          the rectangle within the coded resolution to be output to
> +          ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
> +          hardware without additional compose/scaling capabilities.
> +
> +      ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
> +          the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
> +          frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
> +          hardware does not support compose/scaling.
> +
> +      ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
> +          equal to ``V4L2_SEL_TGT_CROP``.
> +
> +      ``V4L2_SEL_TGT_COMPOSE``
> +          the rectangle inside a ``CAPTURE`` buffer into which the cropped
> +          frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> +          read-only on hardware without additional compose/scaling capabilities.
> +
> +      ``V4L2_SEL_TGT_COMPOSE_PADDED``
> +          the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
> +          hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
> +          write padding pixels.
> +
> +    .. warning::
> +
> +       The values are guaranteed to be meaningful only after the decoder
> +       successfully parses the stream metadata. The client must not rely on the
> +       query before that happens.
> +
> +3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
> +    the ``CAPTURE`` queue. Once the stream information is parsed and known, the
> +    client may use this ioctl to discover which raw formats are supported for
> +    given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
> +
> +    .. important::
> +
> +       The decoder will return only formats supported for the currently
> +       established coded format, as per the ``OUTPUT`` format and/or stream
> +       metadata parsed in this initialization sequence, even if more formats
> +       may be supported by the decoder in general. In other words, the set
> +       returned will be a subset of the initial query mentioned in the
> +       `Querying capabilities` section.
> +
> +       For example, a decoder may support YUV and RGB formats for resolutions
> +       1920x1088 and lower, but only YUV for higher resolutions (due to
> +       hardware limitations). After parsing a resolution of 1920x1088 or lower,
> +       :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
> +       but after parsing resolution higher than 1920x1088, the decoder will not
> +       return RGB, unsupported for this resolution.
> +
> +       However, subsequent resolution change event triggered after
> +       discovering a resolution change within the same stream may switch
> +       the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
> +       would return RGB formats again in that case.
> +
> +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
> +    ``CAPTURE`` queue. The client may choose a different format than
> +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
> +
> +    * **Required fields:**
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``pixelformat``
> +          a raw pixel format.
> +
> +   * Setting the ``CAPTURE`` format will reset the compose selection rectangles
> +     to their default values, based on the new resolution, as described in the
> +     previous step.
> +
> +5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
> +   the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
> +   scaling capabilities.
> +
> +   * **Required fields:**
> +
> +     ``type``
> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +     ``target``
> +         set to ``V4L2_SEL_TGT_COMPOSE``.
> +
> +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> +         the rectangle inside a ``CAPTURE`` buffer into which the cropped
> +         frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> +         read-only on hardware without additional compose/scaling capabilities.
> +
> +   * **Return fields:**
> +
> +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> +         the visible rectangle; it must fit within the frame buffer resolution
> +         returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> +
> +   .. warning::
> +
> +      The decoder may adjust the compose rectangle to the nearest
> +      supported one to meet codec and hardware requirements. The client needs
> +      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
> +
> +6.  If all the following conditions are met, the client may resume the decoding
> +    instantly:
> +
> +    * ``sizeimage`` of the new format (determined in previous steps) is less
> +      than or equal to the size of currently allocated buffers,
> +
> +    * the number of buffers currently allocated is greater than or equal to the
> +      minimum number of buffers acquired in previous steps. To fulfill this
> +      requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
> +      buffers.
> +
> +    In that case, the remaining steps do not apply and the client may resume
> +    the decoding by one of the following actions:
> +
> +    * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
> +      with the ``V4L2_DEC_CMD_START`` command,
> +
> +    * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
> +      on the ``CAPTURE`` queue.
> +
> +    However, if the client intends to change the buffer set, to lower
> +    memory usage or for any other reasons, it may be achieved by following
> +    the steps below.
> +
> +7.  **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
> +    buffers on the ``CAPTURE`` queue until a buffer marked with the
> +    ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
> +
> +8.  **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
> +    on the ``CAPTURE`` queue to stop streaming.
> +
> +    .. warning::
> +
> +       The ``OUTPUT`` queue must remain streaming. Calling
> +       :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
> +       seek.
> +
> +9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
> +    buffers using :c:func:`VIDIOC_REQBUFS`.
> +
> +    * **Required fields:**
> +
> +      ``count``
> +          set to 0.
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``memory``
> +          follows standard semantics.
> +
> +10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
> +    ``CAPTURE`` queue.
> +
> +    * **Required fields:**
> +
> +      ``count``
> +          requested number of buffers to allocate; greater than zero.
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``memory``
> +          follows standard semantics.
> +
> +    * **Return fields:**
> +
> +      ``count``
> +          actual number of buffers allocated.
> +
> +    .. warning::
> +
> +       The actual number of allocated buffers may differ from the ``count``
> +       given. The client must check the updated value of ``count`` after the
> +       call returns.
> +
> +    .. note::
> +
> +       To allocate more than the minimum number of buffers (for pipeline
> +       depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
> +       control to get the minimum number of buffers required, and pass the
> +       obtained value plus the number of additional buffers needed in the
> +       ``count`` field to :c:func:`VIDIOC_REQBUFS`.
> +
> +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
> +    used to have more control over buffer allocation. For example, by
> +    allocating buffers larger than the current ``CAPTURE`` format, future
> +    resolution changes can be accommodated.
> +
> +    * **Required fields:**
> +
> +      ``count``
> +          requested number of buffers to allocate; greater than zero.
> +
> +      ``type``
> +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> +
> +      ``memory``
> +          follows standard semantics.
> +
> +      ``format``
> +          a format representing the maximum framebuffer resolution to be
> +          accommodated by newly allocated buffers.
> +
> +    * **Return fields:**
> +
> +      ``count``
> +          adjusted to the number of allocated buffers.
> +
> +    .. warning::
> +
> +        The actual number of allocated buffers may differ from the ``count``
> +        given. The client must check the updated value of ``count`` after the
> +        call returns.
> +
> +    .. note::
> +
> +       To allocate buffers for a format different than parsed from the stream
> +       metadata, the client must proceed as follows, before the metadata
> +       parsing is initiated:
> +
> +       * set width and height of the ``OUTPUT`` format to desired coded resolution to
> +         let the decoder configure the ``CAPTURE`` format appropriately,
> +
> +       * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
> +         until this step.
> +
> +       The format obtained in the query may be then used with
> +       :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
> +
> +11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
> +    frames.
> +
> +Decoding
> +========
> +
> +This state is reached after the `Capture setup` sequence finishes successfully.
> +In this state, the client queues and dequeues buffers to both queues via
> +:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
> +semantics.
> +
> +The content of the source ``OUTPUT`` buffers depends on the active coded pixel
> +format and may be affected by codec-specific extended controls, as stated in
> +the documentation of each format.
> +
> +Both queues operate independently, following the standard behavior of V4L2
> +buffer queues and memory-to-memory devices. In addition, the order of decoded
> +frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
> +coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
> +format, e.g. frame reordering.
> +
> +The client must not assume any direct relationship between ``CAPTURE``
> +and ``OUTPUT`` buffers and any specific timing of buffers becoming
> +available to dequeue. Specifically:
> +
> +* a buffer queued to ``OUTPUT`` may result in no buffers being produced
> +  on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
> +  metadata syntax structures are present in it),
> +
> +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
> +  on ``CAPTURE`` (if the encoded data contained more than one frame, or if
> +  returning a decoded frame allowed the decoder to return a frame that
> +  preceded it in decode, but succeeded it in the display order),
> +
> +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
> +  ``CAPTURE`` later into decode process, and/or after processing further
> +  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
> +  reordering is used,
> +
> +* buffers may become available on the ``CAPTURE`` queue without additional
> +  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
> +  ``OUTPUT`` buffers queued in the past whose decoding results are only
> +  available at later time, due to specifics of the decoding process.
> +
> +.. note::
> +
> +   To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
> +   originated from, the client can set the ``timestamp`` field of the
> +   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
> +   ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
> +   will have their ``timestamp`` field set to the same value when dequeued.
> +
> +   In addition to the straightforward case of one ``OUTPUT`` buffer producing
> +   one ``CAPTURE`` buffer, the following cases are defined:
> +
> +   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
> +     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
> +
> +   * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
> +     the ``OUTPUT`` buffer queued last will be copied.

I'd like to propose to change this into " timestamp of the OUTPUT
buffer queued first will be copied". The rationale is the following, if
you have an OUTPUT buffer that is unaligned in the following form:

  [ remaining | complete frame ]

The remaining data is the last bits of the current frame. So it should
share a timestamp with the bits that came before. But then you have
another frame which by accident could fit entirely in your buffer. With
the last approach, it is not possible to give that frame a timestamp.

The first approach fixes this problem. If there was a remaining on the
very first buffer, it will be dropped anyway, so it also work for this
case. This modification is aligned with MPEG TS container specification
which says the the timestamp of the packet applies to the first ES
packet that starts, the remaining bits will reuse the previous packet
timestamp. The rest is common sense, e.g. the same ES packet should
only have one timestamp etc.

> +
> +   * the decoding order differs from the display order (i.e. the ``CAPTURE``
> +     buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
> +     timestamps will not retain the order of ``OUTPUT`` timestamps.
> +
> +During the decoding, the decoder may initiate one of the special sequences, as
> +listed below. The sequences will result in the decoder returning all the
> +``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
> +before the sequence started. Last of the buffers will have the
> +``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
> +must check if there is any pending event and:
> +
> +* if a ``V4L2_EVENT_SOURCE_CHANGE`` event is pending, the `Dynamic resolution
> +  change` sequence needs to be followed,
> +
> +* if a ``V4L2_EVENT_EOS`` event is pending, the `End of stream` sequence needs
> +  to be followed.
> +
> +Some of the sequences can be intermixed with each other and need to be handled
> +as they happen. The exact operation is documented for each sequence.
> +
> +Should a decoding error occur, it will be reported to the client with the level
> +of details depending on the decoder capabilities. Specifically:
> +
> +* the CAPTURE buffer that contains the results of the failed decode operation
> +  will be returned with the V4L2_BUF_FLAG_ERROR flag set,
> +
> +* if the decoder is able to precisely report the OUTPUT buffer that triggered
> +  the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
> +  set.
> +
> +In case of a fatal failure that does not allow the decoding to continue, any
> +further operations on corresponding decoder file handle will return the -EIO
> +error code. The client may close the file handle and open a new one, or
> +alternatively reinitialize the instance by stopping streaming on both queues,
> +releasing all buffers and performing the Initialization sequence again.
> +
> +Seek
> +====
> +
> +Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
> +The seek does not require any specific operation on the ``CAPTURE`` queue, but
> +it may be affected as per normal decoder operation.
> +
> +1. Stop the ``OUTPUT`` queue to begin the seek sequence via
> +   :c:func:`VIDIOC_STREAMOFF`.
> +
> +   * **Required fields:**
> +
> +     ``type``
> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> +
> +   * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
> +     treated as returned to the client (following standard semantics).
> +
> +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`
> +
> +   * **Required fields:**
> +
> +     ``type``
> +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> +
> +   * The decoder will start accepting new source bitstream buffers after the
> +     call returns.
> +
> +3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
> +   queue until a suitable resume point is found.
> +
> +   .. note::
> +
> +      There is no requirement to begin queuing coded data starting exactly
> +      from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
> +      buffers will be processed and returned to the client until a suitable
> +      resume point is found.  While looking for a resume point, the decoder
> +      should not produce any decoded frames into ``CAPTURE`` buffers.
> +
> +      Some hardware is known to mishandle seeks to a non-resume point. Such an
> +      operation may result in an unspecified number of corrupted decoded frames
> +      being made available on the ``CAPTURE`` queue. Drivers must ensure that
> +      no fatal decoding errors or crashes occur, and implement any necessary
> +      handling and workarounds for hardware issues related to seek operations.
> +
> +   .. warning::
> +
> +      In case of the H.264/HEVC codec, the client must take care not to seek
> +      over a change of SPS/PPS. Even though the target frame could be a
> +      keyframe, the stale SPS/PPS inside decoder state would lead to undefined
> +      results when decoding. Although the decoder must handle that case without
> +      a crash or a fatal decode error, the client must not expect a sensible
> +      decode output.
> +
> +      If the hardware can detect such corrupted decoded frames, then
> +      corresponding buffers will be returned to the client with the
> +      V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
> +      description of decode error reporting.
> +
> +4. After a resume point is found, the decoder will start returning ``CAPTURE``
> +   buffers containing decoded frames.
> +
> +.. important::
> +
> +   A seek may result in the `Dynamic resolution change` sequence being
> +   initiated, due to the seek target having decoding parameters different from
> +   the part of the stream decoded before the seek. The sequence must be handled
> +   as per normal decoder operation.
> +
> +.. warning::
> +
> +   It is not specified when the ``CAPTURE`` queue starts producing buffers
> +   containing decoded data from the ``OUTPUT`` buffers queued after the seek,
> +   as it operates independently from the ``OUTPUT`` queue.
> +
> +   The decoder may return a number of remaining ``CAPTURE`` buffers containing
> +   decoded frames originating from the ``OUTPUT`` buffers queued before the
> +   seek sequence is performed.
> +
> +   The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
> +   ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
> +   queued before the seek sequence may have matching ``CAPTURE`` buffers
> +   produced.  For example, given the sequence of operations on the
> +   ``OUTPUT`` queue:
> +
> +     QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
> +
> +   any of the following results on the ``CAPTURE`` queue is allowed:
> +
> +     {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}.
> +
> +   To determine the CAPTURE buffer containing the first decoded frame after the
> +   seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
> +   buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
> +   decoder.
> +
> +.. note::
> +
> +   To achieve instantaneous seek, the client may restart streaming on the
> +   ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
> +
> +Dynamic resolution change
> +=========================
> +
> +Streams that include resolution metadata in the bitstream may require switching
> +to a different resolution during the decoding.
> +
> +The sequence starts when the decoder detects a coded frame with one or more of
> +the following parameters different from those previously established (and
> +reflected by corresponding queries):
> +
> +* coded resolution (``OUTPUT`` width and height),
> +
> +* visible resolution (selection rectangles),
> +
> +* the minimum number of buffers needed for decoding.
> +
> +Whenever that happens, the decoder must proceed as follows:
> +
> +1.  After encountering a resolution change in the stream, the decoder sends a
> +    ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
> +    ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> +
> +    .. important::
> +
> +       Any client query issued after the decoder queues the event will return
> +       values applying to the stream after the resolution change, including
> +       queue formats, selection rectangles and controls.
> +
> +2.  The decoder will then process and decode all remaining buffers from before
> +    the resolution change point.
> +
> +    * The last buffer from before the change must be marked with the
> +      ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
> +
> +    .. warning::
> +
> +       The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
> +       = 0) and in that case it must be ignored by the client, as it does not
> +       contain a decoded frame.
> +
> +    .. note::
> +
> +       Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
> +       with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
> +       :c:func:`VIDIOC_DQBUF`.
> +
> +The client must continue the sequence as described below to continue the
> +decoding process.
> +
> +1.  Dequeue the source change event.
> +
> +    .. important::
> +
> +       A source change triggers an implicit decoder drain, similar to the
> +       explicit `Drain` sequence. The decoder is stopped after it completes.
> +       The decoding process must be resumed with either a pair of calls to
> +       :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> +       ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
> +       ``V4L2_DEC_CMD_START`` command.
> +
> +2.  Continue with the `Capture setup` sequence.
> +
> +.. note::
> +
> +   During the resolution change sequence, the ``OUTPUT`` queue must remain
> +   streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
> +   abort the sequence and initiate a seek.
> +
> +   In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
> +   queue and this remains true for the duration of the entire resolution change
> +   sequence as well.
> +
> +   The client should, for best performance and simplicity, keep queuing/dequeuing
> +   buffers to/from the ``OUTPUT`` queue even while processing this sequence.
> +
> +Drain
> +=====
> +
> +To ensure that all queued ``OUTPUT`` buffers have been processed and related
> +``CAPTURE`` buffers are given to the client, the client must follow the drain
> +sequence described below. After the drain sequence ends, the client has
> +received all decoded frames for all ``OUTPUT`` buffers queued before the
> +sequence was started.
> +
> +1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
> +
> +   * **Required fields:**
> +
> +     ``cmd``
> +         set to ``V4L2_DEC_CMD_STOP``.
> +
> +     ``flags``
> +         set to 0.
> +
> +     ``pts``
> +         set to 0.
> +
> +   .. warning::
> +
> +      The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
> +      queues are streaming. For compatibility reasons, the call to
> +      :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
> +      not streaming, but at the same time it will not initiate the `Drain`
> +      sequence and so the steps described below would not be applicable.
> +
> +2. Any ``OUTPUT`` buffers queued by the client before the
> +   :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
> +   normal. The client must continue to handle both queues independently,
> +   similarly to normal decode operation. This includes:
> +
> +   * handling any operations triggered as a result of processing those buffers,
> +     such as the `Dynamic resolution change` sequence, before continuing with
> +     the drain sequence,
> +
> +   * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
> +     ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
> +
> +     .. warning::
> +
> +        The last buffer may be empty (with :c:type:`v4l2_buffer`
> +        ``bytesused`` = 0) and in that case it must be ignored by the client,
> +        as it does not contain a decoded frame.
> +
> +     .. note::
> +
> +        Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
> +        marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
> +        :c:func:`VIDIOC_DQBUF`.
> +
> +   * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
> +     before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
> +
> +   * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
> +
> +   .. note::
> +
> +      For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
> +      event when the last frame has been decoded and all frames are ready to be
> +      dequeued. It is a deprecated behavior and the client must not rely on it.
> +      The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
> +
> +3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
> +   are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
> +   stopped and it will accept, but not process, any newly queued ``OUTPUT``
> +   buffers until the client issues any of the following operations:
> +
> +   * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
> +     operation normally, with all the state from before the drain,
> +
> +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> +     ``CAPTURE`` queue - the decoder will resume the operation normally,
> +     however any ``CAPTURE`` buffers still in the queue will be returned to the
> +     client,
> +
> +   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
> +     ``OUTPUT`` queue - any pending source buffers will be returned to the
> +     client and the `Seek` sequence will be triggered.
> +
> +.. note::
> +
> +   Once the drain sequence is initiated, the client needs to drive it to
> +   completion, as described by the steps above, unless it aborts the process by
> +   issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
> +   queues.  The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
> +   ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
> +   will fail with -EBUSY error code if attempted.
> +
> +   Although mandatory, the availability of decoder commands may be queried
> +   using :c:func:`VIDIOC_TRY_DECODER_CMD`.
> +
> +End of stream
> +=============
> +
> +If the decoder encounters an end of stream marking in the stream, the decoder
> +will initiate the `Drain` sequence, which the client must handle as described
> +above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
> +
> +Commit points
> +=============
> +
> +Setting formats and allocating buffers trigger changes in the behavior of the
> +decoder.
> +
> +1. Setting the format on the ``OUTPUT`` queue may change the set of formats
> +   supported/advertised on the ``CAPTURE`` queue. In particular, it also means
> +   that the ``CAPTURE`` format may be reset and the client must not rely on the
> +   previously set format being preserved.
> +
> +2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
> +   supported for the current ``OUTPUT`` format.
> +
> +3. Setting the format on the ``CAPTURE`` queue does not change the list of
> +   formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
> +   format that is not supported for the currently selected ``OUTPUT`` format
> +   will result in the decoder adjusting the requested ``CAPTURE`` format to a
> +   supported one.
> +
> +4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
> +   supported coded formats, irrespectively of the current ``CAPTURE`` format.
> +
> +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
> +   the client must not change the format on the ``OUTPUT`` queue. Drivers will
> +   return the -EBUSY error code for any such format change attempt.
> +
> +To summarize, setting formats and allocation must always start with the
> +``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
> +set of supported formats for the ``CAPTURE`` queue.
> diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> index 67a980818dc8..caa05f5f6380 100644
> --- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
> +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> @@ -39,4 +39,10 @@ file handle is visible through another file handle).
>  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
> diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> index 71eebfc6d853..caf14e440447 100644
> --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
> @@ -39,6 +39,11 @@ Single-planar format structure
>  	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.
> diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> index 004ec00db6bd..97015b9b40b8 100644
> --- a/Documentation/media/uapi/v4l/v4l2.rst
> +++ b/Documentation/media/uapi/v4l/v4l2.rst
> @@ -60,6 +60,10 @@ Authors, in alphabetical order:
>  
>    - 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.
> @@ -68,6 +72,10 @@ Authors, in alphabetical order:
>  
>    - 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.
> @@ -92,7 +100,7 @@ Authors, in alphabetical order:
>  
>    - 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.
> diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> index ccf83b05afa7..57f0066f4cff 100644
> --- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
> @@ -56,14 +56,16 @@ The ``cmd`` field must contain the command code. Some commands use the
>  
>  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}|
> @@ -167,26 +169,32 @@ introduced in Linux 3.3.
>  	``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
> @@ -209,6 +217,11 @@ 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.
>  
> +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.
>  

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Tomasz Figa]

On Wed, Jul 17, 2019 at 9:18 PM Nicolas Dufresne <nicolas@ndufresne.ca> wrote:
>
> Hello,
>
> there is one little detail/proposal, see inline .
>
> Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> > From: Tomasz Figa <tfiga@chromium.org>
> >
> > Due to complexity of the video decoding process, the V4L2 drivers of
> > stateful decoder hardware require specific sequences of V4L2 API calls
> > to be followed. These include capability enumeration, initialization,
> > decoding, seek, pause, dynamic resolution change, drain and end of
> > stream.
> >
> > Specifics of the above have been discussed during Media Workshops at
> > LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
> > Conference Europe 2014 in Düsseldorf. The de facto Codec API that
> > originated at those events was later implemented by the drivers we already
> > have merged in mainline, such as s5p-mfc or coda.
> >
> > The only thing missing was the real specification included as a part of
> > Linux Media documentation. Fix it now and document the decoder part of
> > the Codec API.
> >
> > Signed-off-by: Tomasz Figa <tfiga@chromium.org>
> > Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> > ---
> >  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
> >  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
> >  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
> >  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
> >  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
> >  5 files changed, 1132 insertions(+), 16 deletions(-)
> >  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> >
> > diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst
> > new file mode 100644
> > index 000000000000..b106f2d97c48
> > --- /dev/null
> > +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
> > @@ -0,0 +1,1084 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +.. _decoder:
> > +
> > +*************************************************
> > +Memory-to-memory Stateful Video Decoder Interface
> > +*************************************************
> > +
> > +A stateful video decoder takes complete chunks of the bitstream (e.g. Annex-B
> > +H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
> > +display order. The decoder is expected not to require any additional information
> > +from the client to process these buffers.
> > +
> > +Performing software parsing, processing etc. of the stream in the driver in
> > +order to support this interface is strongly discouraged. In case such
> > +operations are needed, use of the Stateless Video Decoder Interface (in
> > +development) is strongly advised.
> > +
> > +Conventions and notation used in this document
> > +==============================================
> > +
> > +1. The general V4L2 API rules apply if not specified in this document
> > +   otherwise.
> > +
> > +2. The meaning of words "must", "may", "should", etc. is as per `RFC
> > +   2119 <https://tools.ietf.org/html/rfc2119>`_.
> > +
> > +3. All steps not marked "optional" are required.
> > +
> > +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
> > +   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
> > +   unless specified otherwise.
> > +
> > +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
> > +   used interchangeably with multi-planar API, unless specified otherwise,
> > +   depending on decoder capabilities and following the general V4L2 guidelines.
> > +
> > +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
> > +   [0..2]: i = 0, 1, 2.
> > +
> > +7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
> > +   queue containing data that resulted from processing buffer A.
> > +
> > +.. _decoder-glossary:
> > +
> > +Glossary
> > +========
> > +
> > +CAPTURE
> > +   the destination buffer queue; for decoders, the queue of buffers containing
> > +   decoded frames; for encoders, the queue of buffers containing an encoded
> > +   bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
> > +   ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
> > +   into ``CAPTURE`` buffers.
> > +
> > +client
> > +   the application communicating with the decoder or encoder implementing
> > +   this interface.
> > +
> > +coded format
> > +   encoded/compressed video bitstream format (e.g. H.264, VP8, etc.); see
> > +   also: raw format.
> > +
> > +coded height
> > +   height for given coded resolution.
> > +
> > +coded resolution
> > +   stream resolution in pixels aligned to codec and hardware requirements;
> > +   typically visible resolution rounded up to full macroblocks;
> > +   see also: visible resolution.
> > +
> > +coded width
> > +   width for given coded resolution.
> > +
> > +decode order
> > +   the order in which frames are decoded; may differ from display order if the
> > +   coded format includes a feature of frame reordering; for decoders,
> > +   ``OUTPUT`` buffers must be queued by the client in decode order; for
> > +   encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
> > +
> > +destination
> > +   data resulting from the decode process; see ``CAPTURE``.
> > +
> > +display order
> > +   the order in which frames must be displayed; for encoders, ``OUTPUT``
> > +   buffers must be queued by the client in display order; for decoders,
> > +   ``CAPTURE`` buffers must be returned by the decoder in display order.
> > +
> > +DPB
> > +   Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
> > +   raw frame available for reference in further decoding steps.
> > +
> > +EOS
> > +   end of stream.
> > +
> > +IDR
> > +   Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
> > +   stream, which clears the list of earlier reference frames (DPBs).
> > +
> > +keyframe
> > +   an encoded frame that does not reference frames decoded earlier, i.e.
> > +   can be decoded fully on its own.
> > +
> > +macroblock
> > +   a processing unit in image and video compression formats based on linear
> > +   block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
> > +   popular codecs the size is 16x16 samples (pixels).
> > +
> > +OUTPUT
> > +   the source buffer queue; for decoders, the queue of buffers containing
> > +   an encoded bitstream; for encoders, the queue of buffers containing raw
> > +   frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
> > +   ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
> > +   from ``OUTPUT`` buffers.
> > +
> > +PPS
> > +   Picture Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> > +
> > +raw format
> > +   uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
> > +
> > +resume point
> > +   a point in the bitstream from which decoding may start/continue, without
> > +   any previous state/data present, e.g.: a keyframe (VP8/VP9) or
> > +   SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
> > +   of a new stream, or to resume decoding after a seek.
> > +
> > +source
> > +   data fed to the decoder or encoder; see ``OUTPUT``.
> > +
> > +source height
> > +   height in pixels for given source resolution; relevant to encoders only.
> > +
> > +source resolution
> > +   resolution in pixels of source frames being source to the encoder and
> > +   subject to further cropping to the bounds of visible resolution; relevant to
> > +   encoders only.
> > +
> > +source width
> > +   width in pixels for given source resolution; relevant to encoders only.
> > +
> > +SPS
> > +   Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> > +
> > +stream metadata
> > +   additional (non-visual) information contained inside encoded bitstream;
> > +   for example: coded resolution, visible resolution, codec profile.
> > +
> > +visible height
> > +   height for given visible resolution; display height.
> > +
> > +visible resolution
> > +   stream resolution of the visible picture, in pixels, to be used for
> > +   display purposes; must be smaller or equal to coded resolution;
> > +   display resolution.
> > +
> > +visible width
> > +   width for given visible resolution; display width.
> > +
> > +State machine
> > +=============
> > +
> > +.. kernel-render:: DOT
> > +   :alt: DOT digraph of decoder state machine
> > +   :caption: Decoder state machine
> > +
> > +   digraph decoder_state_machine {
> > +       node [shape = doublecircle, label="Decoding"] Decoding;
> > +
> > +       node [shape = circle, label="Initialization"] Initialization;
> > +       node [shape = circle, label="Capture\nsetup"] CaptureSetup;
> > +       node [shape = circle, label="Dynamic\nresolution\nchange"] ResChange;
> > +       node [shape = circle, label="Stopped"] Stopped;
> > +       node [shape = circle, label="Drain"] Drain;
> > +       node [shape = circle, label="Seek"] Seek;
> > +       node [shape = circle, label="End of stream"] EoS;
> > +
> > +       node [shape = point]; qi
> > +       qi -> Initialization [ label = "open()" ];
> > +
> > +       Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> > +
> > +       CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
> > +
> > +       Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
> > +       Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
> > +       Decoding -> EoS [ label = "EoS mark\nin the stream" ];
> > +       Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > +       Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
> > +       Decoding -> Decoding;
> > +
> > +       ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> > +       ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > +
> > +       EoS -> Drain [ label = "Implicit\ndrain" ];
> > +
> > +       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
> > +       Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > +
> > +       Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
> > +       Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
> > +
> > +       Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
> > +       Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > +   }
> > +
> > +Querying capabilities
> > +=====================
> > +
> > +1. To enumerate the set of coded formats supported by the decoder, the
> > +   client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
> > +
> > +   * The full set of supported formats will be returned, regardless of the
> > +     format set on ``CAPTURE``.
> > +
> > +2. To enumerate the set of supported raw formats, the client may call
> > +   :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
> > +
> > +   * Only the formats supported for the format currently active on ``OUTPUT``
> > +     will be returned.
> > +
> > +   * In order to enumerate raw formats supported by a given coded format,
> > +     the client must first set that coded format on ``OUTPUT`` and then
> > +     enumerate formats on ``CAPTURE``.
> > +
> > +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
> > +   resolutions for a given format, passing desired pixel format in
> > +   :c:type:`v4l2_frmsizeenum` ``pixel_format``.
> > +
> > +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
> > +     format will include all possible coded resolutions supported by the
> > +     decoder for given coded pixel format.
> > +
> > +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
> > +     will include all possible frame buffer resolutions supported by the
> > +     decoder for given raw pixel format and the coded format currently set on
> > +     ``OUTPUT``.
> > +
> > +4. Supported profiles and levels for the coded format currently set on
> > +   ``OUTPUT``, if applicable, may be queried using their respective controls
> > +   via :c:func:`VIDIOC_QUERYCTRL`.
> > +
> > +Initialization
> > +==============
> > +
> > +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
> > +
> > +   * **Required fields:**
> > +
> > +     ``type``
> > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > +
> > +     ``pixelformat``
> > +         a coded pixel format.
> > +
> > +     ``width``, ``height``
> > +         coded resolution of the stream; required only if it cannot be parsed
> > +         from the stream for the given coded format; otherwise the decoder will
> > +         use this resolution as a placeholder resolution that will likely change
> > +         as soon as it can parse the actual coded resolution from the stream.
> > +
> > +     ``sizeimage``
> > +         desired size of ``OUTPUT`` buffers; the decoder may adjust it to
> > +         match hardware requirements.
> > +
> > +     other fields
> > +         follow standard semantics.
> > +
> > +   * **Return fields:**
> > +
> > +     ``sizeimage``
> > +         adjusted size of ``OUTPUT`` buffers.
> > +
> > +   * The ``CAPTURE`` format will be updated with an appropriate frame buffer
> > +     resolution instantly based on the width and height returned by
> > +     :c:func:`VIDIOC_S_FMT`.
> > +     However, for coded formats that include stream resolution information,
> > +     after the decoder is done parsing the information from the stream, it will
> > +     update the ``CAPTURE`` format with new values and signal a source change
> > +     event, regardless of whether they match the values set by the client or
> > +     not.
> > +
> > +   .. important::
> > +
> > +      Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
> > +      format. How the new ``CAPTURE`` format is determined is up to the decoder
> > +      and the client must ensure it matches its needs afterwards.
> > +
> > +2.  Allocate source (bitstream) buffers via :c:func:`VIDIOC_REQBUFS` on
> > +    ``OUTPUT``.
> > +
> > +    * **Required fields:**
> > +
> > +      ``count``
> > +          requested number of buffers to allocate; greater than zero.
> > +
> > +      ``type``
> > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > +
> > +      ``memory``
> > +          follows standard semantics.
> > +
> > +    * **Return fields:**
> > +
> > +      ``count``
> > +          the actual number of buffers allocated.
> > +
> > +    .. warning::
> > +
> > +       The actual number of allocated buffers may differ from the ``count``
> > +       given. The client must check the updated value of ``count`` after the
> > +       call returns.
> > +
> > +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
> > +    used to have more control over buffer allocation.
> > +
> > +    * **Required fields:**
> > +
> > +      ``count``
> > +          requested number of buffers to allocate; greater than zero.
> > +
> > +      ``type``
> > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > +
> > +      ``memory``
> > +          follows standard semantics.
> > +
> > +      ``format``
> > +          follows standard semantics.
> > +
> > +    * **Return fields:**
> > +
> > +      ``count``
> > +          adjusted to the number of allocated buffers.
> > +
> > +    .. warning::
> > +
> > +       The actual number of allocated buffers may differ from the ``count``
> > +       given. The client must check the updated value of ``count`` after the
> > +       call returns.
> > +
> > +3.  Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
> > +
> > +4.  **This step only applies to coded formats that contain resolution information
> > +    in the stream.** Continue queuing/dequeuing bitstream buffers to/from the
> > +    ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
> > +    buffers will be processed and returned to the client in order, until
> > +    required metadata to configure the ``CAPTURE`` queue are found. This is
> > +    indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
> > +    ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> > +
> > +    * It is not an error if the first buffer does not contain enough data for
> > +      this to occur. Processing of the buffers will continue as long as more
> > +      data is needed.
> > +
> > +    * If data in a buffer that triggers the event is required to decode the
> > +      first frame, it will not be returned to the client, until the
> > +      initialization sequence completes and the frame is decoded.
> > +
> > +    * If the client has not set the coded resolution of the stream on its own,
> > +      calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
> > +      :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
> > +      queue will not return the real values for the stream until a
> > +      ``V4L2_EVENT_SOURCE_CHANGE`` event is signaled.
> > +
> > +    .. important::
> > +
> > +       Any client query issued after the decoder queues the event will return
> > +       values applying to the just parsed stream, including queue formats,
> > +       selection rectangles and controls.
> > +
> > +    .. note::
> > +
> > +       A client capable of acquiring stream parameters from the bitstream on
> > +       its own may attempt to set the width and height of the ``OUTPUT`` format
> > +       to non-zero values matching the coded size of the stream, skip this step
> > +       and continue with the `Capture setup` sequence. However, it must not
> > +       rely on any driver queries regarding stream parameters, such as
> > +       selection rectangles and controls, since the decoder has not parsed them
> > +       from the stream yet. If the values configured by the client do not match
> > +       those parsed by the decoder, a `Dynamic resolution change` will be
> > +       triggered to reconfigure them.
> > +
> > +    .. note::
> > +
> > +       No decoded frames are produced during this phase.
> > +
> > +5.  Continue with the `Capture setup` sequence.
> > +
> > +Capture setup
> > +=============
> > +
> > +1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
> > +    destination buffers parsed/decoded from the bitstream.
> > +
> > +    * **Required fields:**
> > +
> > +      ``type``
> > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > +
> > +    * **Return fields:**
> > +
> > +      ``width``, ``height``
> > +          frame buffer resolution for the decoded frames.
> > +
> > +      ``pixelformat``
> > +          pixel format for decoded frames.
> > +
> > +      ``num_planes`` (for _MPLANE ``type`` only)
> > +          number of planes for pixelformat.
> > +
> > +      ``sizeimage``, ``bytesperline``
> > +          as per standard semantics; matching frame buffer format.
> > +
> > +    .. note::
> > +
> > +       The value of ``pixelformat`` may be any pixel format supported by the
> > +       decoder for the current stream. The decoder should choose a
> > +       preferred/optimal format for the default configuration. For example, a
> > +       YUV format may be preferred over an RGB format if an additional
> > +       conversion step would be required for the latter.
> > +
> > +2.  **Optional.** Acquire the visible resolution via
> > +    :c:func:`VIDIOC_G_SELECTION`.
> > +
> > +    * **Required fields:**
> > +
> > +      ``type``
> > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > +
> > +      ``target``
> > +          set to ``V4L2_SEL_TGT_COMPOSE``.
> > +
> > +    * **Return fields:**
> > +
> > +      ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > +          the visible rectangle; it must fit within the frame buffer resolution
> > +          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> > +
> > +    * The following selection targets are supported on ``CAPTURE``:
> > +
> > +      ``V4L2_SEL_TGT_CROP_BOUNDS``
> > +          corresponds to the coded resolution of the stream.
> > +
> > +      ``V4L2_SEL_TGT_CROP_DEFAULT``
> > +          the rectangle covering the part of the ``CAPTURE`` buffer that
> > +          contains meaningful picture data (visible area); width and height
> > +          will be equal to the visible resolution of the stream.
> > +
> > +      ``V4L2_SEL_TGT_CROP``
> > +          the rectangle within the coded resolution to be output to
> > +          ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
> > +          hardware without additional compose/scaling capabilities.
> > +
> > +      ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
> > +          the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
> > +          frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
> > +          hardware does not support compose/scaling.
> > +
> > +      ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
> > +          equal to ``V4L2_SEL_TGT_CROP``.
> > +
> > +      ``V4L2_SEL_TGT_COMPOSE``
> > +          the rectangle inside a ``CAPTURE`` buffer into which the cropped
> > +          frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> > +          read-only on hardware without additional compose/scaling capabilities.
> > +
> > +      ``V4L2_SEL_TGT_COMPOSE_PADDED``
> > +          the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
> > +          hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
> > +          write padding pixels.
> > +
> > +    .. warning::
> > +
> > +       The values are guaranteed to be meaningful only after the decoder
> > +       successfully parses the stream metadata. The client must not rely on the
> > +       query before that happens.
> > +
> > +3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
> > +    the ``CAPTURE`` queue. Once the stream information is parsed and known, the
> > +    client may use this ioctl to discover which raw formats are supported for
> > +    given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
> > +
> > +    .. important::
> > +
> > +       The decoder will return only formats supported for the currently
> > +       established coded format, as per the ``OUTPUT`` format and/or stream
> > +       metadata parsed in this initialization sequence, even if more formats
> > +       may be supported by the decoder in general. In other words, the set
> > +       returned will be a subset of the initial query mentioned in the
> > +       `Querying capabilities` section.
> > +
> > +       For example, a decoder may support YUV and RGB formats for resolutions
> > +       1920x1088 and lower, but only YUV for higher resolutions (due to
> > +       hardware limitations). After parsing a resolution of 1920x1088 or lower,
> > +       :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
> > +       but after parsing resolution higher than 1920x1088, the decoder will not
> > +       return RGB, unsupported for this resolution.
> > +
> > +       However, subsequent resolution change event triggered after
> > +       discovering a resolution change within the same stream may switch
> > +       the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
> > +       would return RGB formats again in that case.
> > +
> > +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
> > +    ``CAPTURE`` queue. The client may choose a different format than
> > +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
> > +
> > +    * **Required fields:**
> > +
> > +      ``type``
> > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > +
> > +      ``pixelformat``
> > +          a raw pixel format.
> > +
> > +   * Setting the ``CAPTURE`` format will reset the compose selection rectangles
> > +     to their default values, based on the new resolution, as described in the
> > +     previous step.
> > +
> > +5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
> > +   the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
> > +   scaling capabilities.
> > +
> > +   * **Required fields:**
> > +
> > +     ``type``
> > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > +
> > +     ``target``
> > +         set to ``V4L2_SEL_TGT_COMPOSE``.
> > +
> > +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > +         the rectangle inside a ``CAPTURE`` buffer into which the cropped
> > +         frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> > +         read-only on hardware without additional compose/scaling capabilities.
> > +
> > +   * **Return fields:**
> > +
> > +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > +         the visible rectangle; it must fit within the frame buffer resolution
> > +         returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> > +
> > +   .. warning::
> > +
> > +      The decoder may adjust the compose rectangle to the nearest
> > +      supported one to meet codec and hardware requirements. The client needs
> > +      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
> > +
> > +6.  If all the following conditions are met, the client may resume the decoding
> > +    instantly:
> > +
> > +    * ``sizeimage`` of the new format (determined in previous steps) is less
> > +      than or equal to the size of currently allocated buffers,
> > +
> > +    * the number of buffers currently allocated is greater than or equal to the
> > +      minimum number of buffers acquired in previous steps. To fulfill this
> > +      requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
> > +      buffers.
> > +
> > +    In that case, the remaining steps do not apply and the client may resume
> > +    the decoding by one of the following actions:
> > +
> > +    * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
> > +      with the ``V4L2_DEC_CMD_START`` command,
> > +
> > +    * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
> > +      on the ``CAPTURE`` queue.
> > +
> > +    However, if the client intends to change the buffer set, to lower
> > +    memory usage or for any other reasons, it may be achieved by following
> > +    the steps below.
> > +
> > +7.  **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
> > +    buffers on the ``CAPTURE`` queue until a buffer marked with the
> > +    ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
> > +
> > +8.  **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
> > +    on the ``CAPTURE`` queue to stop streaming.
> > +
> > +    .. warning::
> > +
> > +       The ``OUTPUT`` queue must remain streaming. Calling
> > +       :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
> > +       seek.
> > +
> > +9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
> > +    buffers using :c:func:`VIDIOC_REQBUFS`.
> > +
> > +    * **Required fields:**
> > +
> > +      ``count``
> > +          set to 0.
> > +
> > +      ``type``
> > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > +
> > +      ``memory``
> > +          follows standard semantics.
> > +
> > +10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
> > +    ``CAPTURE`` queue.
> > +
> > +    * **Required fields:**
> > +
> > +      ``count``
> > +          requested number of buffers to allocate; greater than zero.
> > +
> > +      ``type``
> > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > +
> > +      ``memory``
> > +          follows standard semantics.
> > +
> > +    * **Return fields:**
> > +
> > +      ``count``
> > +          actual number of buffers allocated.
> > +
> > +    .. warning::
> > +
> > +       The actual number of allocated buffers may differ from the ``count``
> > +       given. The client must check the updated value of ``count`` after the
> > +       call returns.
> > +
> > +    .. note::
> > +
> > +       To allocate more than the minimum number of buffers (for pipeline
> > +       depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
> > +       control to get the minimum number of buffers required, and pass the
> > +       obtained value plus the number of additional buffers needed in the
> > +       ``count`` field to :c:func:`VIDIOC_REQBUFS`.
> > +
> > +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
> > +    used to have more control over buffer allocation. For example, by
> > +    allocating buffers larger than the current ``CAPTURE`` format, future
> > +    resolution changes can be accommodated.
> > +
> > +    * **Required fields:**
> > +
> > +      ``count``
> > +          requested number of buffers to allocate; greater than zero.
> > +
> > +      ``type``
> > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > +
> > +      ``memory``
> > +          follows standard semantics.
> > +
> > +      ``format``
> > +          a format representing the maximum framebuffer resolution to be
> > +          accommodated by newly allocated buffers.
> > +
> > +    * **Return fields:**
> > +
> > +      ``count``
> > +          adjusted to the number of allocated buffers.
> > +
> > +    .. warning::
> > +
> > +        The actual number of allocated buffers may differ from the ``count``
> > +        given. The client must check the updated value of ``count`` after the
> > +        call returns.
> > +
> > +    .. note::
> > +
> > +       To allocate buffers for a format different than parsed from the stream
> > +       metadata, the client must proceed as follows, before the metadata
> > +       parsing is initiated:
> > +
> > +       * set width and height of the ``OUTPUT`` format to desired coded resolution to
> > +         let the decoder configure the ``CAPTURE`` format appropriately,
> > +
> > +       * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
> > +         until this step.
> > +
> > +       The format obtained in the query may be then used with
> > +       :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
> > +
> > +11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
> > +    frames.
> > +
> > +Decoding
> > +========
> > +
> > +This state is reached after the `Capture setup` sequence finishes successfully.
> > +In this state, the client queues and dequeues buffers to both queues via
> > +:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
> > +semantics.
> > +
> > +The content of the source ``OUTPUT`` buffers depends on the active coded pixel
> > +format and may be affected by codec-specific extended controls, as stated in
> > +the documentation of each format.
> > +
> > +Both queues operate independently, following the standard behavior of V4L2
> > +buffer queues and memory-to-memory devices. In addition, the order of decoded
> > +frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
> > +coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
> > +format, e.g. frame reordering.
> > +
> > +The client must not assume any direct relationship between ``CAPTURE``
> > +and ``OUTPUT`` buffers and any specific timing of buffers becoming
> > +available to dequeue. Specifically:
> > +
> > +* a buffer queued to ``OUTPUT`` may result in no buffers being produced
> > +  on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
> > +  metadata syntax structures are present in it),
> > +
> > +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
> > +  on ``CAPTURE`` (if the encoded data contained more than one frame, or if
> > +  returning a decoded frame allowed the decoder to return a frame that
> > +  preceded it in decode, but succeeded it in the display order),
> > +
> > +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
> > +  ``CAPTURE`` later into decode process, and/or after processing further
> > +  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
> > +  reordering is used,
> > +
> > +* buffers may become available on the ``CAPTURE`` queue without additional
> > +  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
> > +  ``OUTPUT`` buffers queued in the past whose decoding results are only
> > +  available at later time, due to specifics of the decoding process.
> > +
> > +.. note::
> > +
> > +   To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
> > +   originated from, the client can set the ``timestamp`` field of the
> > +   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
> > +   ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
> > +   will have their ``timestamp`` field set to the same value when dequeued.
> > +
> > +   In addition to the straightforward case of one ``OUTPUT`` buffer producing
> > +   one ``CAPTURE`` buffer, the following cases are defined:
> > +
> > +   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
> > +     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
> > +
> > +   * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
> > +     the ``OUTPUT`` buffer queued last will be copied.
>
> I'd like to propose to change this into " timestamp of the OUTPUT
> buffer queued first will be copied". The rationale is the following, if
> you have an OUTPUT buffer that is unaligned in the following form:
>
>   [ remaining | complete frame ]
>
> The remaining data is the last bits of the current frame. So it should
> share a timestamp with the bits that came before. But then you have
> another frame which by accident could fit entirely in your buffer. With
> the last approach, it is not possible to give that frame a timestamp.
>
> The first approach fixes this problem. If there was a remaining on the
> very first buffer, it will be dropped anyway, so it also work for this
> case. This modification is aligned with MPEG TS container specification
> which says the the timestamp of the packet applies to the first ES
> packet that starts, the remaining bits will reuse the previous packet
> timestamp. The rest is common sense, e.g. the same ES packet should
> only have one timestamp etc.

Wouldn't that replace one problem with another? How about the case below?

[ complete frame | partial frame ] [ remaining ]

Best regards,
Tomasz

Re: [PATCHv4 1/2] media: docs-rst: Document memory-to-memory video decoder interface

[Nicolas Dufresne]

[-- Attachment #1: Type: text/plain, Size: 37441 bytes --]

Le vendredi 19 juillet 2019 à 14:45 +0900, Tomasz Figa a écrit :
> On Wed, Jul 17, 2019 at 9:18 PM Nicolas Dufresne <nicolas@ndufresne.ca> wrote:
> > Hello,
> > 
> > there is one little detail/proposal, see inline .
> > 
> > Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> > > From: Tomasz Figa <tfiga@chromium.org>
> > > 
> > > Due to complexity of the video decoding process, the V4L2 drivers of
> > > stateful decoder hardware require specific sequences of V4L2 API calls
> > > to be followed. These include capability enumeration, initialization,
> > > decoding, seek, pause, dynamic resolution change, drain and end of
> > > stream.
> > > 
> > > Specifics of the above have been discussed during Media Workshops at
> > > LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
> > > Conference Europe 2014 in Düsseldorf. The de facto Codec API that
> > > originated at those events was later implemented by the drivers we already
> > > have merged in mainline, such as s5p-mfc or coda.
> > > 
> > > The only thing missing was the real specification included as a part of
> > > Linux Media documentation. Fix it now and document the decoder part of
> > > the Codec API.
> > > 
> > > Signed-off-by: Tomasz Figa <tfiga@chromium.org>
> > > Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> > > ---
> > >  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
> > >  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    8 +-
> > >  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |    5 +
> > >  Documentation/media/uapi/v4l/v4l2.rst         |   10 +-
> > >  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
> > >  5 files changed, 1132 insertions(+), 16 deletions(-)
> > >  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> > > 
> > > diff --git a/Documentation/media/uapi/v4l/dev-decoder.rst b/Documentation/media/uapi/v4l/dev-decoder.rst
> > > new file mode 100644
> > > index 000000000000..b106f2d97c48
> > > --- /dev/null
> > > +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
> > > @@ -0,0 +1,1084 @@
> > > +.. SPDX-License-Identifier: GPL-2.0
> > > +
> > > +.. _decoder:
> > > +
> > > +*************************************************
> > > +Memory-to-memory Stateful Video Decoder Interface
> > > +*************************************************
> > > +
> > > +A stateful video decoder takes complete chunks of the bitstream (e.g. Annex-B
> > > +H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
> > > +display order. The decoder is expected not to require any additional information
> > > +from the client to process these buffers.
> > > +
> > > +Performing software parsing, processing etc. of the stream in the driver in
> > > +order to support this interface is strongly discouraged. In case such
> > > +operations are needed, use of the Stateless Video Decoder Interface (in
> > > +development) is strongly advised.
> > > +
> > > +Conventions and notation used in this document
> > > +==============================================
> > > +
> > > +1. The general V4L2 API rules apply if not specified in this document
> > > +   otherwise.
> > > +
> > > +2. The meaning of words "must", "may", "should", etc. is as per `RFC
> > > +   2119 <https://tools.ietf.org/html/rfc2119>`_.
> > > +
> > > +3. All steps not marked "optional" are required.
> > > +
> > > +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
> > > +   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
> > > +   unless specified otherwise.
> > > +
> > > +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
> > > +   used interchangeably with multi-planar API, unless specified otherwise,
> > > +   depending on decoder capabilities and following the general V4L2 guidelines.
> > > +
> > > +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
> > > +   [0..2]: i = 0, 1, 2.
> > > +
> > > +7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
> > > +   queue containing data that resulted from processing buffer A.
> > > +
> > > +.. _decoder-glossary:
> > > +
> > > +Glossary
> > > +========
> > > +
> > > +CAPTURE
> > > +   the destination buffer queue; for decoders, the queue of buffers containing
> > > +   decoded frames; for encoders, the queue of buffers containing an encoded
> > > +   bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
> > > +   ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
> > > +   into ``CAPTURE`` buffers.
> > > +
> > > +client
> > > +   the application communicating with the decoder or encoder implementing
> > > +   this interface.
> > > +
> > > +coded format
> > > +   encoded/compressed video bitstream format (e.g. H.264, VP8, etc.); see
> > > +   also: raw format.
> > > +
> > > +coded height
> > > +   height for given coded resolution.
> > > +
> > > +coded resolution
> > > +   stream resolution in pixels aligned to codec and hardware requirements;
> > > +   typically visible resolution rounded up to full macroblocks;
> > > +   see also: visible resolution.
> > > +
> > > +coded width
> > > +   width for given coded resolution.
> > > +
> > > +decode order
> > > +   the order in which frames are decoded; may differ from display order if the
> > > +   coded format includes a feature of frame reordering; for decoders,
> > > +   ``OUTPUT`` buffers must be queued by the client in decode order; for
> > > +   encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
> > > +
> > > +destination
> > > +   data resulting from the decode process; see ``CAPTURE``.
> > > +
> > > +display order
> > > +   the order in which frames must be displayed; for encoders, ``OUTPUT``
> > > +   buffers must be queued by the client in display order; for decoders,
> > > +   ``CAPTURE`` buffers must be returned by the decoder in display order.
> > > +
> > > +DPB
> > > +   Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
> > > +   raw frame available for reference in further decoding steps.
> > > +
> > > +EOS
> > > +   end of stream.
> > > +
> > > +IDR
> > > +   Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
> > > +   stream, which clears the list of earlier reference frames (DPBs).
> > > +
> > > +keyframe
> > > +   an encoded frame that does not reference frames decoded earlier, i.e.
> > > +   can be decoded fully on its own.
> > > +
> > > +macroblock
> > > +   a processing unit in image and video compression formats based on linear
> > > +   block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
> > > +   popular codecs the size is 16x16 samples (pixels).
> > > +
> > > +OUTPUT
> > > +   the source buffer queue; for decoders, the queue of buffers containing
> > > +   an encoded bitstream; for encoders, the queue of buffers containing raw
> > > +   frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
> > > +   ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
> > > +   from ``OUTPUT`` buffers.
> > > +
> > > +PPS
> > > +   Picture Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> > > +
> > > +raw format
> > > +   uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
> > > +
> > > +resume point
> > > +   a point in the bitstream from which decoding may start/continue, without
> > > +   any previous state/data present, e.g.: a keyframe (VP8/VP9) or
> > > +   SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
> > > +   of a new stream, or to resume decoding after a seek.
> > > +
> > > +source
> > > +   data fed to the decoder or encoder; see ``OUTPUT``.
> > > +
> > > +source height
> > > +   height in pixels for given source resolution; relevant to encoders only.
> > > +
> > > +source resolution
> > > +   resolution in pixels of source frames being source to the encoder and
> > > +   subject to further cropping to the bounds of visible resolution; relevant to
> > > +   encoders only.
> > > +
> > > +source width
> > > +   width in pixels for given source resolution; relevant to encoders only.
> > > +
> > > +SPS
> > > +   Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bitstream.
> > > +
> > > +stream metadata
> > > +   additional (non-visual) information contained inside encoded bitstream;
> > > +   for example: coded resolution, visible resolution, codec profile.
> > > +
> > > +visible height
> > > +   height for given visible resolution; display height.
> > > +
> > > +visible resolution
> > > +   stream resolution of the visible picture, in pixels, to be used for
> > > +   display purposes; must be smaller or equal to coded resolution;
> > > +   display resolution.
> > > +
> > > +visible width
> > > +   width for given visible resolution; display width.
> > > +
> > > +State machine
> > > +=============
> > > +
> > > +.. kernel-render:: DOT
> > > +   :alt: DOT digraph of decoder state machine
> > > +   :caption: Decoder state machine
> > > +
> > > +   digraph decoder_state_machine {
> > > +       node [shape = doublecircle, label="Decoding"] Decoding;
> > > +
> > > +       node [shape = circle, label="Initialization"] Initialization;
> > > +       node [shape = circle, label="Capture\nsetup"] CaptureSetup;
> > > +       node [shape = circle, label="Dynamic\nresolution\nchange"] ResChange;
> > > +       node [shape = circle, label="Stopped"] Stopped;
> > > +       node [shape = circle, label="Drain"] Drain;
> > > +       node [shape = circle, label="Seek"] Seek;
> > > +       node [shape = circle, label="End of stream"] EoS;
> > > +
> > > +       node [shape = point]; qi
> > > +       qi -> Initialization [ label = "open()" ];
> > > +
> > > +       Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> > > +
> > > +       CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
> > > +
> > > +       Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
> > > +       Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
> > > +       Decoding -> EoS [ label = "EoS mark\nin the stream" ];
> > > +       Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > +       Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
> > > +       Decoding -> Decoding;
> > > +
> > > +       ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
> > > +       ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > +
> > > +       EoS -> Drain [ label = "Implicit\ndrain" ];
> > > +
> > > +       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
> > > +       Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > +
> > > +       Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
> > > +       Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
> > > +
> > > +       Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
> > > +       Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
> > > +   }
> > > +
> > > +Querying capabilities
> > > +=====================
> > > +
> > > +1. To enumerate the set of coded formats supported by the decoder, the
> > > +   client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
> > > +
> > > +   * The full set of supported formats will be returned, regardless of the
> > > +     format set on ``CAPTURE``.
> > > +
> > > +2. To enumerate the set of supported raw formats, the client may call
> > > +   :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
> > > +
> > > +   * Only the formats supported for the format currently active on ``OUTPUT``
> > > +     will be returned.
> > > +
> > > +   * In order to enumerate raw formats supported by a given coded format,
> > > +     the client must first set that coded format on ``OUTPUT`` and then
> > > +     enumerate formats on ``CAPTURE``.
> > > +
> > > +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
> > > +   resolutions for a given format, passing desired pixel format in
> > > +   :c:type:`v4l2_frmsizeenum` ``pixel_format``.
> > > +
> > > +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
> > > +     format will include all possible coded resolutions supported by the
> > > +     decoder for given coded pixel format.
> > > +
> > > +   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
> > > +     will include all possible frame buffer resolutions supported by the
> > > +     decoder for given raw pixel format and the coded format currently set on
> > > +     ``OUTPUT``.
> > > +
> > > +4. Supported profiles and levels for the coded format currently set on
> > > +   ``OUTPUT``, if applicable, may be queried using their respective controls
> > > +   via :c:func:`VIDIOC_QUERYCTRL`.
> > > +
> > > +Initialization
> > > +==============
> > > +
> > > +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`
> > > +
> > > +   * **Required fields:**
> > > +
> > > +     ``type``
> > > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > +
> > > +     ``pixelformat``
> > > +         a coded pixel format.
> > > +
> > > +     ``width``, ``height``
> > > +         coded resolution of the stream; required only if it cannot be parsed
> > > +         from the stream for the given coded format; otherwise the decoder will
> > > +         use this resolution as a placeholder resolution that will likely change
> > > +         as soon as it can parse the actual coded resolution from the stream.
> > > +
> > > +     ``sizeimage``
> > > +         desired size of ``OUTPUT`` buffers; the decoder may adjust it to
> > > +         match hardware requirements.
> > > +
> > > +     other fields
> > > +         follow standard semantics.
> > > +
> > > +   * **Return fields:**
> > > +
> > > +     ``sizeimage``
> > > +         adjusted size of ``OUTPUT`` buffers.
> > > +
> > > +   * The ``CAPTURE`` format will be updated with an appropriate frame buffer
> > > +     resolution instantly based on the width and height returned by
> > > +     :c:func:`VIDIOC_S_FMT`.
> > > +     However, for coded formats that include stream resolution information,
> > > +     after the decoder is done parsing the information from the stream, it will
> > > +     update the ``CAPTURE`` format with new values and signal a source change
> > > +     event, regardless of whether they match the values set by the client or
> > > +     not.
> > > +
> > > +   .. important::
> > > +
> > > +      Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
> > > +      format. How the new ``CAPTURE`` format is determined is up to the decoder
> > > +      and the client must ensure it matches its needs afterwards.
> > > +
> > > +2.  Allocate source (bitstream) buffers via :c:func:`VIDIOC_REQBUFS` on
> > > +    ``OUTPUT``.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``count``
> > > +          requested number of buffers to allocate; greater than zero.
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > +
> > > +      ``memory``
> > > +          follows standard semantics.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``count``
> > > +          the actual number of buffers allocated.
> > > +
> > > +    .. warning::
> > > +
> > > +       The actual number of allocated buffers may differ from the ``count``
> > > +       given. The client must check the updated value of ``count`` after the
> > > +       call returns.
> > > +
> > > +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
> > > +    used to have more control over buffer allocation.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``count``
> > > +          requested number of buffers to allocate; greater than zero.
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
> > > +
> > > +      ``memory``
> > > +          follows standard semantics.
> > > +
> > > +      ``format``
> > > +          follows standard semantics.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``count``
> > > +          adjusted to the number of allocated buffers.
> > > +
> > > +    .. warning::
> > > +
> > > +       The actual number of allocated buffers may differ from the ``count``
> > > +       given. The client must check the updated value of ``count`` after the
> > > +       call returns.
> > > +
> > > +3.  Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
> > > +
> > > +4.  **This step only applies to coded formats that contain resolution information
> > > +    in the stream.** Continue queuing/dequeuing bitstream buffers to/from the
> > > +    ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
> > > +    buffers will be processed and returned to the client in order, until
> > > +    required metadata to configure the ``CAPTURE`` queue are found. This is
> > > +    indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
> > > +    ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
> > > +
> > > +    * It is not an error if the first buffer does not contain enough data for
> > > +      this to occur. Processing of the buffers will continue as long as more
> > > +      data is needed.
> > > +
> > > +    * If data in a buffer that triggers the event is required to decode the
> > > +      first frame, it will not be returned to the client, until the
> > > +      initialization sequence completes and the frame is decoded.
> > > +
> > > +    * If the client has not set the coded resolution of the stream on its own,
> > > +      calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
> > > +      :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
> > > +      queue will not return the real values for the stream until a
> > > +      ``V4L2_EVENT_SOURCE_CHANGE`` event is signaled.
> > > +
> > > +    .. important::
> > > +
> > > +       Any client query issued after the decoder queues the event will return
> > > +       values applying to the just parsed stream, including queue formats,
> > > +       selection rectangles and controls.
> > > +
> > > +    .. note::
> > > +
> > > +       A client capable of acquiring stream parameters from the bitstream on
> > > +       its own may attempt to set the width and height of the ``OUTPUT`` format
> > > +       to non-zero values matching the coded size of the stream, skip this step
> > > +       and continue with the `Capture setup` sequence. However, it must not
> > > +       rely on any driver queries regarding stream parameters, such as
> > > +       selection rectangles and controls, since the decoder has not parsed them
> > > +       from the stream yet. If the values configured by the client do not match
> > > +       those parsed by the decoder, a `Dynamic resolution change` will be
> > > +       triggered to reconfigure them.
> > > +
> > > +    .. note::
> > > +
> > > +       No decoded frames are produced during this phase.
> > > +
> > > +5.  Continue with the `Capture setup` sequence.
> > > +
> > > +Capture setup
> > > +=============
> > > +
> > > +1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
> > > +    destination buffers parsed/decoded from the bitstream.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``width``, ``height``
> > > +          frame buffer resolution for the decoded frames.
> > > +
> > > +      ``pixelformat``
> > > +          pixel format for decoded frames.
> > > +
> > > +      ``num_planes`` (for _MPLANE ``type`` only)
> > > +          number of planes for pixelformat.
> > > +
> > > +      ``sizeimage``, ``bytesperline``
> > > +          as per standard semantics; matching frame buffer format.
> > > +
> > > +    .. note::
> > > +
> > > +       The value of ``pixelformat`` may be any pixel format supported by the
> > > +       decoder for the current stream. The decoder should choose a
> > > +       preferred/optimal format for the default configuration. For example, a
> > > +       YUV format may be preferred over an RGB format if an additional
> > > +       conversion step would be required for the latter.
> > > +
> > > +2.  **Optional.** Acquire the visible resolution via
> > > +    :c:func:`VIDIOC_G_SELECTION`.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +      ``target``
> > > +          set to ``V4L2_SEL_TGT_COMPOSE``.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > > +          the visible rectangle; it must fit within the frame buffer resolution
> > > +          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> > > +
> > > +    * The following selection targets are supported on ``CAPTURE``:
> > > +
> > > +      ``V4L2_SEL_TGT_CROP_BOUNDS``
> > > +          corresponds to the coded resolution of the stream.
> > > +
> > > +      ``V4L2_SEL_TGT_CROP_DEFAULT``
> > > +          the rectangle covering the part of the ``CAPTURE`` buffer that
> > > +          contains meaningful picture data (visible area); width and height
> > > +          will be equal to the visible resolution of the stream.
> > > +
> > > +      ``V4L2_SEL_TGT_CROP``
> > > +          the rectangle within the coded resolution to be output to
> > > +          ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
> > > +          hardware without additional compose/scaling capabilities.
> > > +
> > > +      ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
> > > +          the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
> > > +          frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
> > > +          hardware does not support compose/scaling.
> > > +
> > > +      ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
> > > +          equal to ``V4L2_SEL_TGT_CROP``.
> > > +
> > > +      ``V4L2_SEL_TGT_COMPOSE``
> > > +          the rectangle inside a ``CAPTURE`` buffer into which the cropped
> > > +          frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> > > +          read-only on hardware without additional compose/scaling capabilities.
> > > +
> > > +      ``V4L2_SEL_TGT_COMPOSE_PADDED``
> > > +          the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
> > > +          hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
> > > +          write padding pixels.
> > > +
> > > +    .. warning::
> > > +
> > > +       The values are guaranteed to be meaningful only after the decoder
> > > +       successfully parses the stream metadata. The client must not rely on the
> > > +       query before that happens.
> > > +
> > > +3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
> > > +    the ``CAPTURE`` queue. Once the stream information is parsed and known, the
> > > +    client may use this ioctl to discover which raw formats are supported for
> > > +    given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
> > > +
> > > +    .. important::
> > > +
> > > +       The decoder will return only formats supported for the currently
> > > +       established coded format, as per the ``OUTPUT`` format and/or stream
> > > +       metadata parsed in this initialization sequence, even if more formats
> > > +       may be supported by the decoder in general. In other words, the set
> > > +       returned will be a subset of the initial query mentioned in the
> > > +       `Querying capabilities` section.
> > > +
> > > +       For example, a decoder may support YUV and RGB formats for resolutions
> > > +       1920x1088 and lower, but only YUV for higher resolutions (due to
> > > +       hardware limitations). After parsing a resolution of 1920x1088 or lower,
> > > +       :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
> > > +       but after parsing resolution higher than 1920x1088, the decoder will not
> > > +       return RGB, unsupported for this resolution.
> > > +
> > > +       However, subsequent resolution change event triggered after
> > > +       discovering a resolution change within the same stream may switch
> > > +       the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
> > > +       would return RGB formats again in that case.
> > > +
> > > +4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
> > > +    ``CAPTURE`` queue. The client may choose a different format than
> > > +    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +      ``pixelformat``
> > > +          a raw pixel format.
> > > +
> > > +   * Setting the ``CAPTURE`` format will reset the compose selection rectangles
> > > +     to their default values, based on the new resolution, as described in the
> > > +     previous step.
> > > +
> > > +5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
> > > +   the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
> > > +   scaling capabilities.
> > > +
> > > +   * **Required fields:**
> > > +
> > > +     ``type``
> > > +         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +     ``target``
> > > +         set to ``V4L2_SEL_TGT_COMPOSE``.
> > > +
> > > +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > > +         the rectangle inside a ``CAPTURE`` buffer into which the cropped
> > > +         frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
> > > +         read-only on hardware without additional compose/scaling capabilities.
> > > +
> > > +   * **Return fields:**
> > > +
> > > +     ``r.left``, ``r.top``, ``r.width``, ``r.height``
> > > +         the visible rectangle; it must fit within the frame buffer resolution
> > > +         returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
> > > +
> > > +   .. warning::
> > > +
> > > +      The decoder may adjust the compose rectangle to the nearest
> > > +      supported one to meet codec and hardware requirements. The client needs
> > > +      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
> > > +
> > > +6.  If all the following conditions are met, the client may resume the decoding
> > > +    instantly:
> > > +
> > > +    * ``sizeimage`` of the new format (determined in previous steps) is less
> > > +      than or equal to the size of currently allocated buffers,
> > > +
> > > +    * the number of buffers currently allocated is greater than or equal to the
> > > +      minimum number of buffers acquired in previous steps. To fulfill this
> > > +      requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
> > > +      buffers.
> > > +
> > > +    In that case, the remaining steps do not apply and the client may resume
> > > +    the decoding by one of the following actions:
> > > +
> > > +    * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
> > > +      with the ``V4L2_DEC_CMD_START`` command,
> > > +
> > > +    * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
> > > +      on the ``CAPTURE`` queue.
> > > +
> > > +    However, if the client intends to change the buffer set, to lower
> > > +    memory usage or for any other reasons, it may be achieved by following
> > > +    the steps below.
> > > +
> > > +7.  **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
> > > +    buffers on the ``CAPTURE`` queue until a buffer marked with the
> > > +    ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
> > > +
> > > +8.  **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
> > > +    on the ``CAPTURE`` queue to stop streaming.
> > > +
> > > +    .. warning::
> > > +
> > > +       The ``OUTPUT`` queue must remain streaming. Calling
> > > +       :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
> > > +       seek.
> > > +
> > > +9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
> > > +    buffers using :c:func:`VIDIOC_REQBUFS`.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``count``
> > > +          set to 0.
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +      ``memory``
> > > +          follows standard semantics.
> > > +
> > > +10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
> > > +    ``CAPTURE`` queue.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``count``
> > > +          requested number of buffers to allocate; greater than zero.
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +      ``memory``
> > > +          follows standard semantics.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``count``
> > > +          actual number of buffers allocated.
> > > +
> > > +    .. warning::
> > > +
> > > +       The actual number of allocated buffers may differ from the ``count``
> > > +       given. The client must check the updated value of ``count`` after the
> > > +       call returns.
> > > +
> > > +    .. note::
> > > +
> > > +       To allocate more than the minimum number of buffers (for pipeline
> > > +       depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
> > > +       control to get the minimum number of buffers required, and pass the
> > > +       obtained value plus the number of additional buffers needed in the
> > > +       ``count`` field to :c:func:`VIDIOC_REQBUFS`.
> > > +
> > > +    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
> > > +    used to have more control over buffer allocation. For example, by
> > > +    allocating buffers larger than the current ``CAPTURE`` format, future
> > > +    resolution changes can be accommodated.
> > > +
> > > +    * **Required fields:**
> > > +
> > > +      ``count``
> > > +          requested number of buffers to allocate; greater than zero.
> > > +
> > > +      ``type``
> > > +          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
> > > +
> > > +      ``memory``
> > > +          follows standard semantics.
> > > +
> > > +      ``format``
> > > +          a format representing the maximum framebuffer resolution to be
> > > +          accommodated by newly allocated buffers.
> > > +
> > > +    * **Return fields:**
> > > +
> > > +      ``count``
> > > +          adjusted to the number of allocated buffers.
> > > +
> > > +    .. warning::
> > > +
> > > +        The actual number of allocated buffers may differ from the ``count``
> > > +        given. The client must check the updated value of ``count`` after the
> > > +        call returns.
> > > +
> > > +    .. note::
> > > +
> > > +       To allocate buffers for a format different than parsed from the stream
> > > +       metadata, the client must proceed as follows, before the metadata
> > > +       parsing is initiated:
> > > +
> > > +       * set width and height of the ``OUTPUT`` format to desired coded resolution to
> > > +         let the decoder configure the ``CAPTURE`` format appropriately,
> > > +
> > > +       * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
> > > +         until this step.
> > > +
> > > +       The format obtained in the query may be then used with
> > > +       :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
> > > +
> > > +11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
> > > +    frames.
> > > +
> > > +Decoding
> > > +========
> > > +
> > > +This state is reached after the `Capture setup` sequence finishes successfully.
> > > +In this state, the client queues and dequeues buffers to both queues via
> > > +:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
> > > +semantics.
> > > +
> > > +The content of the source ``OUTPUT`` buffers depends on the active coded pixel
> > > +format and may be affected by codec-specific extended controls, as stated in
> > > +the documentation of each format.
> > > +
> > > +Both queues operate independently, following the standard behavior of V4L2
> > > +buffer queues and memory-to-memory devices. In addition, the order of decoded
> > > +frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
> > > +coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
> > > +format, e.g. frame reordering.
> > > +
> > > +The client must not assume any direct relationship between ``CAPTURE``
> > > +and ``OUTPUT`` buffers and any specific timing of buffers becoming
> > > +available to dequeue. Specifically:
> > > +
> > > +* a buffer queued to ``OUTPUT`` may result in no buffers being produced
> > > +  on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
> > > +  metadata syntax structures are present in it),
> > > +
> > > +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
> > > +  on ``CAPTURE`` (if the encoded data contained more than one frame, or if
> > > +  returning a decoded frame allowed the decoder to return a frame that
> > > +  preceded it in decode, but succeeded it in the display order),
> > > +
> > > +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
> > > +  ``CAPTURE`` later into decode process, and/or after processing further
> > > +  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
> > > +  reordering is used,
> > > +
> > > +* buffers may become available on the ``CAPTURE`` queue without additional
> > > +  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
> > > +  ``OUTPUT`` buffers queued in the past whose decoding results are only
> > > +  available at later time, due to specifics of the decoding process.
> > > +
> > > +.. note::
> > > +
> > > +   To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
> > > +   originated from, the client can set the ``timestamp`` field of the
> > > +   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
> > > +   ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
> > > +   will have their ``timestamp`` field set to the same value when dequeued.
> > > +
> > > +   In addition to the straightforward case of one ``OUTPUT`` buffer producing
> > > +   one ``CAPTURE`` buffer, the following cases are defined:
> > > +
> > > +   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
> > > +     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
> > > +
> > > +   * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
> > > +     the ``OUTPUT`` buffer queued last will be copied.
> > 
> > I'd like to propose to change this into " timestamp of the OUTPUT
> > buffer queued first will be copied". The rationale is the following, if
> > you have an OUTPUT buffer that is unaligned in the following form:
> > 
> >   [ remaining | complete frame ]
> > 
> > The remaining data is the last bits of the current frame. So it should
> > share a timestamp with the bits that came before. But then you have
> > another frame which by accident could fit entirely in your buffer. With
> > the last approach, it is not possible to give that frame a timestamp.
> > 
> > The first approach fixes this problem. If there was a remaining on the
> > very first buffer, it will be dropped anyway, so it also work for this
> > case. This modification is aligned with MPEG TS container specification
> > which says the the timestamp of the packet applies to the first ES
> > packet that starts, the remaining bits will reuse the previous packet
> > timestamp. The rest is common sense, e.g. the same ES packet should
> > only have one timestamp etc.
> 
> Wouldn't that replace one problem with another? How about the case below?
> 
> [ complete frame | partial frame ] [ remaining ]

Right, both methods are kind of bad (even though I still like sticking
with something used elsewhere). Personally, I think it's probably not
worth giving that case a standard and it could be left undefined.

> 
> Best regards,
> Tomasz

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

[PATCHv4 2/2] media: docs-rst: Document memory-to-memory video encoder interface

[Hans Verkuil]

From: Tomasz Figa <tfiga@chromium.org>

Due to complexity of the video encoding process, the V4L2 drivers of
stateful encoder hardware require specific sequences of V4L2 API calls
to be followed. These include capability enumeration, initialization,
encoding, encode parameters change, drain and reset.

Specifics of the above have been discussed during Media Workshops at
LinuxCon Europe 2012 in Barcelona and then later Embedded Linux
Conference Europe 2014 in Düsseldorf. The de facto Codec API that
originated at those events was later implemented by the drivers we already
have merged in mainline, such as s5p-mfc or coda.

The only thing missing was the real specification included as a part of
Linux Media documentation. Fix it now and document the encoder part of
the Codec API.

Signed-off-by: Tomasz Figa <tfiga@chromium.org>
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
---
 Documentation/media/uapi/v4l/dev-encoder.rst  | 608 ++++++++++++++++++
 Documentation/media/uapi/v4l/dev-mem2mem.rst  |   1 +
 Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |   5 +
 Documentation/media/uapi/v4l/v4l2.rst         |   2 +
 .../media/uapi/v4l/vidioc-encoder-cmd.rst     |  51 +-
 5 files changed, 647 insertions(+), 20 deletions(-)
 create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst

diff --git a/Documentation/media/uapi/v4l/dev-encoder.rst b/Documentation/media/uapi/v4l/dev-encoder.rst
new file mode 100644
index 000000000000..e3ef31bfed56
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-encoder.rst
@@ -0,0 +1,608 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _encoder:
+
+*************************************************
+Memory-to-memory Stateful Video Encoder Interface
+*************************************************
+
+A stateful video encoder takes raw video frames in display order and encodes
+them into a bitstream. It generates complete chunks of the bitstream, including
+all metadata, headers, etc. The resulting bitstream does not require any
+further post-processing by the client.
+
+Performing software stream processing, header generation etc. in the driver
+in order to support this interface is strongly discouraged. In case such
+operations are needed, use of the Stateless Video Encoder Interface (in
+development) is strongly advised.
+
+Conventions and notation used in this document
+==============================================
+
+1. The general V4L2 API rules apply if not specified in this document
+   otherwise.
+
+2. The meaning of words "must", "may", "should", etc. is as per `RFC
+   2119 <https://tools.ietf.org/html/rfc2119>`_.
+
+3. All steps not marked "optional" are required.
+
+4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
+   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
+   unless specified otherwise.
+
+5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
+   used interchangeably with multi-planar API, unless specified otherwise,
+   depending on encoder capabilities and following the general V4L2 guidelines.
+
+6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
+   [0..2]: i = 0, 1, 2.
+
+7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
+   queue containing data that resulted from processing buffer A.
+
+Glossary
+========
+
+Refer to :ref:`decoder-glossary`.
+
+State machine
+=============
+
+.. kernel-render:: DOT
+   :alt: DOT digraph of encoder state machine
+   :caption: Encoder state machine
+
+   digraph encoder_state_machine {
+       node [shape = doublecircle, label="Encoding"] Encoding;
+
+       node [shape = circle, label="Initialization"] Initialization;
+       node [shape = circle, label="Stopped"] Stopped;
+       node [shape = circle, label="Drain"] Drain;
+       node [shape = circle, label="Reset"] Reset;
+
+       node [shape = point]; qi
+       qi -> Initialization [ label = "open()" ];
+
+       Initialization -> Encoding [ label = "Both queues streaming" ];
+
+       Encoding -> Drain [ label = "V4L2_ENC_CMD_STOP" ];
+       Encoding -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
+       Encoding -> Stopped [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
+       Encoding -> Encoding;
+
+       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(OUTPUT)" ];
+       Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
+
+       Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ];
+       Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
+
+       Stopped -> Encoding [ label = "V4L2_ENC_CMD_START\nor\nVIDIOC_STREAMON(OUTPUT)" ];
+       Stopped -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
+   }
+
+Querying capabilities
+=====================
+
+1. To enumerate the set of coded formats supported by the encoder, the
+   client may call :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
+
+   * The full set of supported formats will be returned, regardless of the
+     format set on ``OUTPUT``.
+
+2. To enumerate the set of supported raw formats, the client may call
+   :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
+
+   * Only the formats supported for the format currently active on ``CAPTURE``
+     will be returned.
+
+   * In order to enumerate raw formats supported by a given coded format,
+     the client must first set that coded format on ``CAPTURE`` and then
+     enumerate the formats on ``OUTPUT``.
+
+3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
+   resolutions for a given format, passing desired pixel format in
+   :c:type:`v4l2_frmsizeenum` ``pixel_format``.
+
+   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
+     format will include all possible coded resolutions supported by the
+     encoder for given coded pixel format.
+
+   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
+     will include all possible frame buffer resolutions supported by the
+     encoder for given raw pixel format and coded format currently set on
+     ``CAPTURE``.
+
+4. Supported profiles and levels for the coded format currently set on
+   ``CAPTURE``, if applicable, may be queried using their respective controls
+   via :c:func:`VIDIOC_QUERYCTRL`.
+
+5. Any additional encoder capabilities may be discovered by querying
+   their respective controls.
+
+Initialization
+==============
+
+1. Set the coded format on the ``CAPTURE`` queue via :c:func:`VIDIOC_S_FMT`
+
+   * **Required fields:**
+
+     ``type``
+         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
+
+     ``pixelformat``
+         the coded format to be produced.
+
+     ``sizeimage``
+         desired size of ``CAPTURE`` buffers; the encoder may adjust it to
+         match hardware requirements.
+
+     ``width``, ``height``
+         ignored (read-only).
+
+     other fields
+         follow standard semantics.
+
+   * **Return fields:**
+
+     ``sizeimage``
+         adjusted size of ``CAPTURE`` buffers.
+
+     ``width``, ``height``
+         the coded size selected by the encoder based on current state, e.g.
+         ``OUTPUT`` format, selection rectangles, etc. (read-only).
+
+   .. important::
+
+      Changing the ``CAPTURE`` format may change the currently set ``OUTPUT``
+      format. How the new ``OUTPUT`` format is determined is up to the encoder
+      and the client must ensure it matches its needs afterwards.
+
+2. **Optional.** Enumerate supported ``OUTPUT`` formats (raw formats for
+   source) for the selected coded format via :c:func:`VIDIOC_ENUM_FMT`.
+
+   * **Required fields:**
+
+     ``type``
+         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+     other fields
+         follow standard semantics.
+
+   * **Return fields:**
+
+     ``pixelformat``
+         raw format supported for the coded format currently selected on
+         the ``CAPTURE`` queue.
+
+     other fields
+         follow standard semantics.
+
+3. Set the raw source format on the ``OUTPUT`` queue via
+   :c:func:`VIDIOC_S_FMT`.
+
+   * **Required fields:**
+
+     ``type``
+         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+     ``pixelformat``
+         raw format of the source.
+
+     ``width``, ``height``
+         source resolution.
+
+     other fields
+         follow standard semantics.
+
+   * **Return fields:**
+
+     ``width``, ``height``
+         may be adjusted to match encoder minimums, maximums and alignment
+         requirements, as required by the currently selected formats, as
+         reported by :c:func:`VIDIOC_ENUM_FRAMESIZES`.
+
+     other fields
+         follow standard semantics.
+
+   * Setting the ``OUTPUT`` format will reset the selection rectangles to their
+     default values, based on the new resolution, as described in the next
+     step.
+
+4. **Optional.** Set the visible resolution for the stream metadata via
+   :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue if it is desired
+   to be different than the full OUTPUT resolution.
+
+   * **Required fields:**
+
+     ``type``
+         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+     ``target``
+         set to ``V4L2_SEL_TGT_CROP``.
+
+     ``r.left``, ``r.top``, ``r.width``, ``r.height``
+         visible rectangle; this must fit within the `V4L2_SEL_TGT_CROP_BOUNDS`
+         rectangle and may be subject to adjustment to match codec and
+         hardware constraints.
+
+   * **Return fields:**
+
+     ``r.left``, ``r.top``, ``r.width``, ``r.height``
+         visible rectangle adjusted by the encoder.
+
+   * The following selection targets are supported on ``OUTPUT``:
+
+     ``V4L2_SEL_TGT_CROP_BOUNDS``
+         equal to the full source frame, matching the active ``OUTPUT``
+         format.
+
+     ``V4L2_SEL_TGT_CROP_DEFAULT``
+         equal to ``V4L2_SEL_TGT_CROP_BOUNDS``.
+
+     ``V4L2_SEL_TGT_CROP``
+         rectangle within the source buffer to be encoded into the
+         ``CAPTURE`` stream; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``.
+
+         .. note::
+
+            A common use case for this selection target is encoding a source
+            video with a resolution that is not a multiple of a macroblock,
+            e.g.  the common 1920x1080 resolution may require the source
+            buffers to be aligned to 1920x1088 for codecs with 16x16 macroblock
+            size. To avoid encoding the padding, the client needs to explicitly
+            configure this selection target to 1920x1080.
+
+   .. warning::
+
+      The encoder may adjust the crop/compose rectangles to the nearest
+      supported ones to meet codec and hardware requirements. The client needs
+      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
+
+5. Allocate buffers for both ``OUTPUT`` and ``CAPTURE`` via
+   :c:func:`VIDIOC_REQBUFS`. This may be performed in any order.
+
+   * **Required fields:**
+
+     ``count``
+         requested number of buffers to allocate; greater than zero.
+
+     ``type``
+         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT`` or
+         ``CAPTURE``.
+
+     other fields
+         follow standard semantics.
+
+   * **Return fields:**
+
+     ``count``
+          actual number of buffers allocated.
+
+   .. warning::
+
+      The actual number of allocated buffers may differ from the ``count``
+      given. The client must check the updated value of ``count`` after the
+      call returns.
+
+   .. note::
+
+      To allocate more than the minimum number of OUTPUT buffers (for pipeline
+      depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT``
+      control to get the minimum number of buffers required, and pass the
+      obtained value plus the number of additional buffers needed in the
+      ``count`` field to :c:func:`VIDIOC_REQBUFS`.
+
+   Alternatively, :c:func:`VIDIOC_CREATE_BUFS` can be used to have more
+   control over buffer allocation.
+
+   * **Required fields:**
+
+     ``count``
+         requested number of buffers to allocate; greater than zero.
+
+     ``type``
+         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
+
+     other fields
+         follow standard semantics.
+
+   * **Return fields:**
+
+     ``count``
+         adjusted to the number of allocated buffers.
+
+6. Begin streaming on both ``OUTPUT`` and ``CAPTURE`` queues via
+   :c:func:`VIDIOC_STREAMON`. This may be performed in any order. The actual
+   encoding process starts when both queues start streaming.
+
+.. note::
+
+   If the client stops the ``CAPTURE`` queue during the encode process and then
+   restarts it again, the encoder will begin generating a stream independent
+   from the stream generated before the stop. The exact constraints depend
+   on the coded format, but may include the following implications:
+
+   * encoded frames produced after the restart must not reference any
+     frames produced before the stop, e.g. no long term references for
+     H.264/HEVC,
+
+   * any headers that must be included in a standalone stream must be
+     produced again, e.g. SPS and PPS for H.264/HEVC.
+
+Encoding
+========
+
+This state is reached after the `Initialization` sequence finishes
+successfully.  In this state, the client queues and dequeues buffers to both
+queues via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the
+standard semantics.
+
+The content of encoded ``CAPTURE`` buffers depends on the active coded pixel
+format and may be affected by codec-specific extended controls, as stated
+in the documentation of each format.
+
+Both queues operate independently, following standard behavior of V4L2 buffer
+queues and memory-to-memory devices. In addition, the order of encoded frames
+dequeued from the ``CAPTURE`` queue may differ from the order of queuing raw
+frames to the ``OUTPUT`` queue, due to properties of the selected coded format,
+e.g. frame reordering.
+
+The client must not assume any direct relationship between ``CAPTURE`` and
+``OUTPUT`` buffers and any specific timing of buffers becoming
+available to dequeue. Specifically:
+
+* a buffer queued to ``OUTPUT`` may result in more than one buffer produced on
+  ``CAPTURE`` (if returning an encoded frame allowed the encoder to return a
+  frame that preceded it in display, but succeeded it in the decode order),
+
+* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
+  ``CAPTURE`` later into encode process, and/or after processing further
+  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
+  reordering is used,
+
+* buffers may become available on the ``CAPTURE`` queue without additional
+  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
+  ``OUTPUT`` buffers queued in the past whose decoding results are only
+  available at later time, due to specifics of the decoding process,
+
+* buffers queued to ``OUTPUT`` may not become available to dequeue instantly
+  after being encoded into a corresponding ``CAPTURE`` buffer, e.g. if the
+  encoder needs to use the frame as a reference for encoding further frames.
+
+.. note::
+
+   To allow matching encoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
+   originated from, the client can set the ``timestamp`` field of the
+   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
+   ``CAPTURE`` buffer(s), which resulted from encoding that ``OUTPUT`` buffer
+   will have their ``timestamp`` field set to the same value when dequeued.
+
+   In addition to the straightforward case of one ``OUTPUT`` buffer producing
+   one ``CAPTURE`` buffer, the following cases are defined:
+
+   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
+     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers,
+
+   * the encoding order differs from the presentation order (i.e. the
+     ``CAPTURE`` buffers are out-of-order compared to the ``OUTPUT`` buffers):
+     ``CAPTURE`` timestamps will not retain the order of ``OUTPUT`` timestamps.
+
+.. note::
+
+   To let the client distinguish between frame types (keyframes, intermediate
+   frames; the exact list of types depends on the coded format), the
+   ``CAPTURE`` buffers will have corresponding flag bits set in their
+   :c:type:`v4l2_buffer` struct when dequeued. See the documentation of
+   :c:type:`v4l2_buffer` and each coded pixel format for exact list of flags
+   and their meanings.
+
+Should an encoding error occur, it will be reported to the client with the level
+of details depending on the encoder capabilities. Specifically:
+
+* the CAPTURE buffer (if any) that contains the results of the failed encode
+  operation will be returned with the V4L2_BUF_FLAG_ERROR flag set,
+
+* if the encoder is able to precisely report the OUTPUT buffer(s) that triggered
+  the error, such buffer(s) will be returned with the V4L2_BUF_FLAG_ERROR flag
+  set.
+
+In case of a fatal failure that does not allow the encoding to continue, any
+further operations on corresponding encoder file handle will return the -EIO
+error code. The client may close the file handle and open a new one, or
+alternatively reinitialize the instance by stopping streaming on both queues,
+releasing all buffers and performing the Initialization sequence again.
+
+Encoding parameter changes
+==========================
+
+The client is allowed to use :c:func:`VIDIOC_S_CTRL` to change encoder
+parameters at any time. The availability of parameters is encoder-specific
+and the client must query the encoder to find the set of available controls.
+
+The ability to change each parameter during encoding is encoder-specific, as
+per the standard semantics of the V4L2 control interface. The client may
+attempt to set a control during encoding and if the operation fails with the
+-EBUSY error code, the ``CAPTURE`` queue needs to be stopped for the
+configuration change to be allowed. To do this, it may follow the `Drain`
+sequence to avoid losing the already queued/encoded frames.
+
+The timing of parameter updates is encoder-specific, as per the standard
+semantics of the V4L2 control interface. If the client needs to apply the
+parameters exactly at specific frame, using the Request API
+(:ref:`media-request-api`) should be considered, if supported by the encoder.
+
+Drain
+=====
+
+To ensure that all the queued ``OUTPUT`` buffers have been processed and the
+related ``CAPTURE`` buffers are given to the client, the client must follow the
+drain sequence described below. After the drain sequence ends, the client has
+received all encoded frames for all ``OUTPUT`` buffers queued before the
+sequence was started.
+
+1. Begin the drain sequence by issuing :c:func:`VIDIOC_ENCODER_CMD`.
+
+   * **Required fields:**
+
+     ``cmd``
+         set to ``V4L2_ENC_CMD_STOP``.
+
+     ``flags``
+         set to 0.
+
+     ``pts``
+         set to 0.
+
+   .. warning::
+
+      The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
+      queues are streaming. For compatibility reasons, the call to
+      :c:func:`VIDIOC_ENCODER_CMD` will not fail even if any of the queues is
+      not streaming, but at the same time it will not initiate the `Drain`
+      sequence and so the steps described below would not be applicable.
+
+2. Any ``OUTPUT`` buffers queued by the client before the
+   :c:func:`VIDIOC_ENCODER_CMD` was issued will be processed and encoded as
+   normal. The client must continue to handle both queues independently,
+   similarly to normal encode operation. This includes:
+
+   * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
+     ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
+
+     .. warning::
+
+        The last buffer may be empty (with :c:type:`v4l2_buffer`
+        ``bytesused`` = 0) and in that case it must be ignored by the client,
+        as it does not contain an encoded frame.
+
+     .. note::
+
+        Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
+        marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
+        :c:func:`VIDIOC_DQBUF`.
+
+   * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
+     before the ``V4L2_ENC_CMD_STOP`` command are dequeued,
+
+   * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribes to it.
+
+   .. note::
+
+      For backwards compatibility, the encoder will signal a ``V4L2_EVENT_EOS``
+      event when the last frame has been encoded and all frames are ready to be
+      dequeued. It is deprecated behavior and the client must not rely on it.
+      The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
+
+3. Once all ``OUTPUT`` buffers queued before the ``V4L2_ENC_CMD_STOP`` call are
+   dequeued and the last ``CAPTURE`` buffer is dequeued, the encoder is stopped
+   and it will accept, but not process any newly queued ``OUTPUT`` buffers
+   until the client issues any of the following operations:
+
+   * ``V4L2_ENC_CMD_START`` - the encoder will not be reset and will resume
+     operation normally, with all the state from before the drain,
+
+   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
+     ``CAPTURE`` queue - the encoder will be reset (see the `Reset` sequence)
+     and then resume encoding,
+
+   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
+     ``OUTPUT`` queue - the encoder will resume operation normally, however any
+     source frames queued to the ``OUTPUT`` queue between ``V4L2_ENC_CMD_STOP``
+     and :c:func:`VIDIOC_STREAMOFF` will be discarded.
+
+.. note::
+
+   Once the drain sequence is initiated, the client needs to drive it to
+   completion, as described by the steps above, unless it aborts the process by
+   issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
+   queues.  The client is not allowed to issue ``V4L2_ENC_CMD_START`` or
+   ``V4L2_ENC_CMD_STOP`` again while the drain sequence is in progress and they
+   will fail with -EBUSY error code if attempted.
+
+   For reference, handling of various corner cases is described below:
+
+   * In case of no buffer in the ``OUTPUT`` queue at the time the
+     ``V4L2_ENC_CMD_STOP`` command was issued, the drain sequence completes
+     immediately and the encoder returns an empty ``CAPTURE`` buffer with the
+     ``V4L2_BUF_FLAG_LAST`` flag set.
+
+   * In case of no buffer in the ``CAPTURE`` queue at the time the drain
+     sequence completes, the next time the client queues a ``CAPTURE`` buffer
+     it is returned at once as an empty buffer with the ``V4L2_BUF_FLAG_LAST``
+     flag set.
+
+   * If :c:func:`VIDIOC_STREAMOFF` is called on the ``CAPTURE`` queue in the
+     middle of the drain sequence, the drain sequence is canceled and all
+     ``CAPTURE`` buffers are implicitly returned to the client.
+
+   * If :c:func:`VIDIOC_STREAMOFF` is called on the ``OUTPUT`` queue in the
+     middle of the drain sequence, the drain sequence completes immediately and
+     next ``CAPTURE`` buffer will be returned empty with the
+     ``V4L2_BUF_FLAG_LAST`` flag set.
+
+   Although mandatory, the availability of encoder commands may be queried
+   using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
+
+Reset
+=====
+
+The client may want to request the encoder to reinitialize the encoding, so
+that the following stream data becomes independent from the stream data
+generated before. Depending on the coded format, that may imply that:
+
+* encoded frames produced after the restart must not reference any frames
+  produced before the stop, e.g. no long term references for H.264/HEVC,
+
+* any headers that must be included in a standalone stream must be produced
+  again, e.g. SPS and PPS for H.264/HEVC.
+
+This can be achieved by performing the reset sequence.
+
+1. Perform the `Drain` sequence to ensure all the in-flight encoding finishes
+   and respective buffers are dequeued.
+
+2. Stop streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMOFF`. This
+   will return all currently queued ``CAPTURE`` buffers to the client, without
+   valid frame data.
+
+3. Start streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMON` and
+   continue with regular encoding sequence. The encoded frames produced into
+   ``CAPTURE`` buffers from now on will contain a standalone stream that can be
+   decoded without the need for frames encoded before the reset sequence,
+   starting at the first ``OUTPUT`` buffer queued after issuing the
+   `V4L2_ENC_CMD_STOP` of the `Drain` sequence.
+
+This sequence may be also used to change encoding parameters for encoders
+without the ability to change the parameters on the fly.
+
+Commit points
+=============
+
+Setting formats and allocating buffers triggers changes in the behavior of the
+encoder.
+
+1. Setting the format on the ``CAPTURE`` queue may change the set of formats
+   supported/advertised on the ``OUTPUT`` queue. In particular, it also means
+   that the ``OUTPUT`` format may be reset and the client must not rely on the
+   previously set format being preserved.
+
+2. Enumerating formats on the ``OUTPUT`` queue always returns only formats
+   supported for the current ``CAPTURE`` format.
+
+3. Setting the format on the ``OUTPUT`` queue does not change the list of
+   formats available on the ``CAPTURE`` queue. An attempt to set the ``OUTPUT``
+   format that is not supported for the currently selected ``CAPTURE`` format
+   will result in the encoder adjusting the requested ``OUTPUT`` format to a
+   supported one.
+
+4. Enumerating formats on the ``CAPTURE`` queue always returns the full set of
+   supported coded formats, irrespective of the current ``OUTPUT`` format.
+
+5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
+   the client must not change the format on the ``CAPTURE`` queue. Drivers will
+   return the -EBUSY error code for any such format change attempt.
+
+To summarize, setting formats and allocation must always start with the
+``CAPTURE`` queue and the ``CAPTURE`` queue is the master that governs the
+set of supported formats for the ``OUTPUT`` queue.
diff --git a/Documentation/media/uapi/v4l/dev-mem2mem.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
index caa05f5f6380..14336f766d0e 100644
--- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
+++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
@@ -46,3 +46,4 @@ devices are given in the following sections.
     :maxdepth: 1
 
     dev-decoder
+    dev-encoder
diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
index caf14e440447..593d25b935bf 100644
--- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst
@@ -44,6 +44,11 @@ Single-planar format structure
 	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.
+
+	For compressed formats on the CAPTURE side of a stateful mem2mem
+	encoder, the fields must be zero, since the coded size is expected to
+	be calculated internally by the encoder itself, based on the OUTPUT
+	side. For more details see :ref:`encoder` and format descriptions.
     * - __u32
       - ``pixelformat``
       - The pixel format or type of compression, set by the application.
diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
index 97015b9b40b8..e236ea23481b 100644
--- a/Documentation/media/uapi/v4l/v4l2.rst
+++ b/Documentation/media/uapi/v4l/v4l2.rst
@@ -63,6 +63,7 @@ Authors, in alphabetical order:
 - Figa, Tomasz <tfiga@chromium.org>
 
   - Documented the memory-to-memory decoder interface.
+  - Documented the memory-to-memory encoder interface.
 
 - H Schimek, Michael <mschimek@gmx.at>
 
@@ -75,6 +76,7 @@ Authors, in alphabetical order:
 - Osciak, Pawel <posciak@chromium.org>
 
   - Documented the memory-to-memory decoder interface.
+  - Documented the memory-to-memory encoder interface.
 
 - Osciak, Pawel <pawel@osciak.com>
 
diff --git a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst
index c313ca8b8cb5..88281e707476 100644
--- a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst
+++ b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst
@@ -51,25 +51,26 @@ To send a command applications must initialize all fields of a struct
 ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to
 this structure.
 
-The ``cmd`` field must contain the command code. The ``flags`` field is
-currently only used by the STOP command and contains one bit: If the
-``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue
-until the end of the current *Group Of Pictures*, otherwise it will stop
-immediately.
+The ``cmd`` field must contain the command code. Some commands use the
+``flags`` field for additional information.
 
-A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
-call sends an implicit START command to the encoder if it has not been
-started yet. After a STOP command, :ref:`read() <func-read>` calls will read
+After a STOP command, :ref:`read() <func-read>` calls will read
 the remaining data buffered by the driver. When the buffer is empty,
 :ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>`
 call will restart the encoder.
 
+A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+call sends an implicit START command to the encoder if it has not been
+started yet. Applies to both queues of mem2mem encoders.
+
 A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
 call of a streaming file descriptor sends an implicit immediate STOP to
-the encoder, and all buffered data is discarded.
+the encoder, and all buffered data is discarded. Applies to both queues of
+mem2mem encoders.
 
 These ioctls are optional, not all drivers may support them. They were
-introduced in Linux 2.6.21.
+introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem
+encoders (as further documented in :ref:`encoder`).
 
 
 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -109,21 +110,24 @@ introduced in Linux 2.6.21.
       - 0
       - Start the encoder. When the encoder is already running or paused,
 	this command does nothing. No flags are defined for this command.
+
+	For a device implementing the :ref:`encoder`, once the drain sequence
+	is initiated with the ``V4L2_ENC_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. See :ref:`encoder` for more details.
     * - ``V4L2_ENC_CMD_STOP``
       - 1
       - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
 	is set, encoding will continue until the end of the current *Group
 	Of Pictures*, otherwise encoding will stop immediately. When the
-	encoder is already stopped, this command does nothing. mem2mem
-	encoders will send a ``V4L2_EVENT_EOS`` event when the last frame
-	has been encoded 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.
+	encoder is already stopped, this command does nothing.
+
+	For a device implementing the :ref:`encoder`, the command will initiate
+	the drain sequence as documented in :ref:`encoder`. 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_ENC_CMD_PAUSE``
       - 2
       - Pause the encoder. When the encoder has not been started yet, the
@@ -152,6 +156,8 @@ introduced in Linux 2.6.21.
       - Stop encoding at the end of the current *Group Of Pictures*,
 	rather than immediately.
 
+        Does not apply to :ref:`encoder`.
+
 
 Return Value
 ============
@@ -160,6 +166,11 @@ 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.
 
+EBUSY
+    A drain sequence of a device implementing the :ref:`encoder` is still in
+    progress. It is not allowed to issue another encoder command until it
+    completes.
+
 EINVAL
     The ``cmd`` field is invalid.
 
-- 
2.20.1

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Hans Verkuil]

These changes + the stateless decoder v4 patch are now available here:

https://hverkuil.home.xs4all.nl/codec-api/uapi/v4l/dev-mem2mem.html

Easier to read than a patch :-)

Regards,

	Hans

On 6/3/19 1:28 PM, Hans Verkuil wrote:
> Since Thomasz was very busy with other things, I've taken over this
> patch series. This v4 includes his draft changes and additional changes
> from me.
> 
> This series attempts to add the documentation of what was discussed
> during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
> later Embedded Linux Conference Europe 2014 in Düsseldorf and then
> eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
> video team (but mostly in a cosmetic way or making the document more
> precise), during the several years of Chrome OS using the APIs in
> production.
> 
> Note that most, if not all, of the API is already implemented in
> existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
> this series is just to formalize what we already have.
> 
> Thanks everyone for the huge amount of useful comments to previous
> versions of this series. Much of the credits should go to Pawel Osciak
> too, for writing most of the original text of the initial RFC.
> 
> This v4 incorporates all known comments (let me know if I missed
> something!) and should be complete for the decoder.
> 
> For the encoder there are two remaining TODOs for the API:
> 
> 1) Setting the frame rate so bitrate control can make sense, since
>    they need to know this information.
> 
>    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
>    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
>    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
>    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
>    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.
> 
> 2) Interactions between OUTPUT and CAPTURE formats.
> 
>    The main problem is what to do if the capture sizeimage is too small
>    for the OUTPUT resolution when streaming starts.
> 
>    Proposal: width and height of S_FMT(OUTPUT) are used to
>    calculate a minimum sizeimage (app may request more). This is
>    driver-specific.
> 
>    V4L2_FMT_FLAG_FIXED_RESOLUTION is always set for codec formats
>    for the encoder (i.e. we don't support mid-stream resolution
>    changes for now) and V4L2_EVENT_SOURCE_CHANGE is not
>    supported. See https://patchwork.linuxtv.org/patch/56478/ for
>    the patch adding this flag.
> 
>    Of course, if we start to support mid-stream resolution
>    changes (or other changes that require a source change event),
>    then this flag should be dropped by the encoder driver and
>    documentation on how to handle the source change event should
>    be documented in the encoder spec. I prefer to postpone this
>    until we have an encoder than can actually do mid-stream
>    resolution changes.
> 
>    If sizeimage of the OUTPUT is too small for the CAPTURE
>    resolution and V4L2_EVENT_SOURCE_CHANGE is not supported,
>    then the second STREAMON (either CAPTURE or OUTPUT) will
>    return -ENOMEM since there is not enough memory to do the
>    encode.
> 
>    If V4L2_FMT_FLAG_FIXED_RESOLUTION is set (i.e. that should
>    be the case for all current encoders), then any bitrate controls
>    will be limited in range to what the current state (CAPTURE and
>    OUTPUT formats and frame rate) supports.
> 
> Comments regarding these two encoder proposals are welcome!
> 
> Regards,
> 
> 	Hans
> 
> Changes since v3:
> 
> - Lots of stylistic fixes and fixing typos/grammar/etc.
> 
> Decoder:
> 
> - width/height for S_FMT(OUTPUT):
> 
>   Expects that the output width and height is always a valid
>   resolution (i.e. never 0x0), and G/S/TRY_FMT and REQBUFS will use that
>   instead of returning an error. Note that this resolution is a placeholder
>   until the actual resolution is parsed from the stream.
> 
> - Dropped step 3 (Query the minimum number of buffers required for the CAPTURE
>   queue via VIDIOC_G_CTRL().) in the Capture Setup section. It seems to be
>   a left-over from earlier versions. The same information is also in Step 10,
>   so no need to have this in two places.
> 
> - Added step 5 in the Capture Setup section: set COMPOSE rectangle if needed.
> 
> - VIDIO_DECODER_CMD: document EBUSY return while draining the queue.
> 
> Encoder:
> 
> - width/height for S_FMT(CAPTURE): The width/height for the CAPTURE format
>   are marked as read-only and are based on the encoders current state such
>   as the OUTPUT format.
> 
> - Drop TGT_COMPOSE support in the encoder: there are currently
>   no encoders that can do composing/scaling.
> 
> - Document corner cases in the Drain sequence
> 
> - Document error handling.
> 
> - VIDIO_ENCODER_CMD: document EBUSY return while draining the queue.
> 
> Changes since v2:
> (https://lore.kernel.org/patchwork/cover/1002474/)
> Decoder:
>  - Specified that the initial source change event is signaled
>    regardless of whether the client-set format matches the
>    stream format.
>  - Dropped V4L2_CID_MIN_BUFFERS_FOR_OUTPUT since it's meaningless
>    for the bitstream input buffers of decoders.
>  - Explicitly stated that VIDIOC_REQBUFS is not allowed on CAPTURE
>    if the stream information is not available.
>  - Described decode error handling.
>  - Mentioned that timestamps can be observed after a seek to
>    determine whether the CAPTURE buffers originated from before
>    or after the seek.
>  - Explicitly stated that after a pair of V4L2_DEC_CMD_STOP and
>    V4L2_DEC_CMD_START, the decoder is not reset and preserves
>    all the state.
> 
> Encoder:
>  - Specified that width and height of CAPTURE format are ignored
>    and always zero.
>  - Explicitly noted the common use case for the CROP target with
>    macroblock-unaligned video resolutions.
>  - Added a reference to Request API.
>  - Dropped V4L2_CID_MIN_BUFFERS_FOR_CAPTURE since it's meaningless
>    for the bitstream output buffers of encoders.
>  - Explicitly stated that after a pair of V4L2_ENC_CMD_STOP and
>    V4L2_ENC_CMD_START, the encoder is not reset and preserves
>    all the state.
> 
> General:
>  - Dropped format enumeration from "Initialization", since it's already
>    a part of "Querying capabilities".
>  - Many spelling, grammar, stylistic, etc. changes.
>  - Changed the style of note blocks.
>  - Rebased onto Hans' documentation cleanup series.
>    (https://patchwork.kernel.org/cover/10775407/
>     https://patchwork.kernel.org/patch/10776737/)
>  - Moved the interfaces under the "Video Memory-To-Memory Interface"
>    section.
> 
> For changes since v1 see the v2:
> https://lore.kernel.org/patchwork/cover/1002474/
> 
> For changes since RFC see the v1:
> https://patchwork.kernel.org/cover/10542207/
> 
> Tomasz Figa (2):
>   media: docs-rst: Document memory-to-memory video decoder interface
>   media: docs-rst: Document memory-to-memory video encoder interface
> 
>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
>  Documentation/media/uapi/v4l/dev-encoder.rst  |  608 +++++++++
>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    9 +-
>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |   10 +
>  Documentation/media/uapi/v4l/v4l2.rst         |   12 +-
>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
>  .../media/uapi/v4l/vidioc-encoder-cmd.rst     |   51 +-
>  7 files changed, 1779 insertions(+), 36 deletions(-)
>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>  create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst
> 

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Nicolas Dufresne]

[-- Attachment #1: Type: text/plain, Size: 8207 bytes --]

Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> Since Thomasz was very busy with other things, I've taken over this
> patch series. This v4 includes his draft changes and additional changes
> from me.
> 
> This series attempts to add the documentation of what was discussed
> during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
> later Embedded Linux Conference Europe 2014 in Düsseldorf and then
> eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
> video team (but mostly in a cosmetic way or making the document more
> precise), during the several years of Chrome OS using the APIs in
> production.
> 
> Note that most, if not all, of the API is already implemented in
> existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
> this series is just to formalize what we already have.
> 
> Thanks everyone for the huge amount of useful comments to previous
> versions of this series. Much of the credits should go to Pawel Osciak
> too, for writing most of the original text of the initial RFC.
> 
> This v4 incorporates all known comments (let me know if I missed
> something!) and should be complete for the decoder.
> 
> For the encoder there are two remaining TODOs for the API:
> 
> 1) Setting the frame rate so bitrate control can make sense, since
>    they need to know this information.
> 
>    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
>    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
>    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
>    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
>    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.

I agree, as long as it's documented. I can imagine how this could be
confusing for new users.

> 
> 2) Interactions between OUTPUT and CAPTURE formats.
> 
>    The main problem is what to do if the capture sizeimage is too small
>    for the OUTPUT resolution when streaming starts.
> 
>    Proposal: width and height of S_FMT(OUTPUT) are used to
>    calculate a minimum sizeimage (app may request more). This is
>    driver-specific.
> 
>    V4L2_FMT_FLAG_FIXED_RESOLUTION is always set for codec formats
>    for the encoder (i.e. we don't support mid-stream resolution
>    changes for now) and V4L2_EVENT_SOURCE_CHANGE is not
>    supported. See https://patchwork.linuxtv.org/patch/56478/ for
>    the patch adding this flag.
> 
>    Of course, if we start to support mid-stream resolution
>    changes (or other changes that require a source change event),
>    then this flag should be dropped by the encoder driver and
>    documentation on how to handle the source change event should
>    be documented in the encoder spec. I prefer to postpone this
>    until we have an encoder than can actually do mid-stream
>    resolution changes.
> 
>    If sizeimage of the OUTPUT is too small for the CAPTURE
>    resolution and V4L2_EVENT_SOURCE_CHANGE is not supported,
>    then the second STREAMON (either CAPTURE or OUTPUT) will
>    return -ENOMEM since there is not enough memory to do the
>    encode.

You seem confident that we will know immediately if it's too small. But
what I remember is that HW has an interrupt for this, allowing
userspace to allocate a larger buffer and resume.

Should we make the capture queue independent of the streaming state, so
that we can streamoff/reqbufs/.../streamon to resume from an ENOMEM
error ? And shouldn't ENOMEM be returned by the following capture DQBUF
when such an interrupt is raised ?

> 
>    If V4L2_FMT_FLAG_FIXED_RESOLUTION is set (i.e. that should
>    be the case for all current encoders), then any bitrate controls
>    will be limited in range to what the current state (CAPTURE and
>    OUTPUT formats and frame rate) supports.
> 
> Comments regarding these two encoder proposals are welcome!
> 
> Regards,
> 
> 	Hans
> 
> Changes since v3:
> 
> - Lots of stylistic fixes and fixing typos/grammar/etc.
> 
> Decoder:
> 
> - width/height for S_FMT(OUTPUT):
> 
>   Expects that the output width and height is always a valid
>   resolution (i.e. never 0x0), and G/S/TRY_FMT and REQBUFS will use that
>   instead of returning an error. Note that this resolution is a placeholder
>   until the actual resolution is parsed from the stream.
> 
> - Dropped step 3 (Query the minimum number of buffers required for the CAPTURE
>   queue via VIDIOC_G_CTRL().) in the Capture Setup section. It seems to be
>   a left-over from earlier versions. The same information is also in Step 10,
>   so no need to have this in two places.
> 
> - Added step 5 in the Capture Setup section: set COMPOSE rectangle if needed.
> 
> - VIDIO_DECODER_CMD: document EBUSY return while draining the queue.
> 
> Encoder:
> 
> - width/height for S_FMT(CAPTURE): The width/height for the CAPTURE format
>   are marked as read-only and are based on the encoders current state such
>   as the OUTPUT format.
> 
> - Drop TGT_COMPOSE support in the encoder: there are currently
>   no encoders that can do composing/scaling.
> 
> - Document corner cases in the Drain sequence
> 
> - Document error handling.
> 
> - VIDIO_ENCODER_CMD: document EBUSY return while draining the queue.
> 
> Changes since v2:
> (https://lore.kernel.org/patchwork/cover/1002474/)
> Decoder:
>  - Specified that the initial source change event is signaled
>    regardless of whether the client-set format matches the
>    stream format.
>  - Dropped V4L2_CID_MIN_BUFFERS_FOR_OUTPUT since it's meaningless
>    for the bitstream input buffers of decoders.
>  - Explicitly stated that VIDIOC_REQBUFS is not allowed on CAPTURE
>    if the stream information is not available.
>  - Described decode error handling.
>  - Mentioned that timestamps can be observed after a seek to
>    determine whether the CAPTURE buffers originated from before
>    or after the seek.
>  - Explicitly stated that after a pair of V4L2_DEC_CMD_STOP and
>    V4L2_DEC_CMD_START, the decoder is not reset and preserves
>    all the state.
> 
> Encoder:
>  - Specified that width and height of CAPTURE format are ignored
>    and always zero.
>  - Explicitly noted the common use case for the CROP target with
>    macroblock-unaligned video resolutions.
>  - Added a reference to Request API.
>  - Dropped V4L2_CID_MIN_BUFFERS_FOR_CAPTURE since it's meaningless
>    for the bitstream output buffers of encoders.
>  - Explicitly stated that after a pair of V4L2_ENC_CMD_STOP and
>    V4L2_ENC_CMD_START, the encoder is not reset and preserves
>    all the state.
> 
> General:
>  - Dropped format enumeration from "Initialization", since it's already
>    a part of "Querying capabilities".
>  - Many spelling, grammar, stylistic, etc. changes.
>  - Changed the style of note blocks.
>  - Rebased onto Hans' documentation cleanup series.
>    (https://patchwork.kernel.org/cover/10775407/
>     https://patchwork.kernel.org/patch/10776737/)
>  - Moved the interfaces under the "Video Memory-To-Memory Interface"
>    section.
> 
> For changes since v1 see the v2:
> https://lore.kernel.org/patchwork/cover/1002474/
> 
> For changes since RFC see the v1:
> https://patchwork.kernel.org/cover/10542207/
> 
> Tomasz Figa (2):
>   media: docs-rst: Document memory-to-memory video decoder interface
>   media: docs-rst: Document memory-to-memory video encoder interface
> 
>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
>  Documentation/media/uapi/v4l/dev-encoder.rst  |  608 +++++++++
>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    9 +-
>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |   10 +
>  Documentation/media/uapi/v4l/v4l2.rst         |   12 +-
>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
>  .../media/uapi/v4l/vidioc-encoder-cmd.rst     |   51 +-
>  7 files changed, 1779 insertions(+), 36 deletions(-)
>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>  create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst
> 

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Tomasz Figa]

On Wed, Jun 5, 2019 at 12:19 AM Nicolas Dufresne <nicolas@ndufresne.ca> wrote:
>
> Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> > Since Thomasz was very busy with other things, I've taken over this
> > patch series. This v4 includes his draft changes and additional changes
> > from me.
> >
> > This series attempts to add the documentation of what was discussed
> > during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
> > later Embedded Linux Conference Europe 2014 in Düsseldorf and then
> > eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
> > video team (but mostly in a cosmetic way or making the document more
> > precise), during the several years of Chrome OS using the APIs in
> > production.
> >
> > Note that most, if not all, of the API is already implemented in
> > existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
> > this series is just to formalize what we already have.
> >
> > Thanks everyone for the huge amount of useful comments to previous
> > versions of this series. Much of the credits should go to Pawel Osciak
> > too, for writing most of the original text of the initial RFC.
> >
> > This v4 incorporates all known comments (let me know if I missed
> > something!) and should be complete for the decoder.
> >
> > For the encoder there are two remaining TODOs for the API:
> >
> > 1) Setting the frame rate so bitrate control can make sense, since
> >    they need to know this information.
> >
> >    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
> >    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
> >    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
> >    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
> >    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.
>
> I agree, as long as it's documented. I can imagine how this could be
> confusing for new users.
>
> >
> > 2) Interactions between OUTPUT and CAPTURE formats.
> >
> >    The main problem is what to do if the capture sizeimage is too small
> >    for the OUTPUT resolution when streaming starts.
> >
> >    Proposal: width and height of S_FMT(OUTPUT) are used to
> >    calculate a minimum sizeimage (app may request more). This is
> >    driver-specific.
> >
> >    V4L2_FMT_FLAG_FIXED_RESOLUTION is always set for codec formats
> >    for the encoder (i.e. we don't support mid-stream resolution
> >    changes for now) and V4L2_EVENT_SOURCE_CHANGE is not
> >    supported. See https://patchwork.linuxtv.org/patch/56478/ for
> >    the patch adding this flag.
> >
> >    Of course, if we start to support mid-stream resolution
> >    changes (or other changes that require a source change event),
> >    then this flag should be dropped by the encoder driver and
> >    documentation on how to handle the source change event should
> >    be documented in the encoder spec. I prefer to postpone this
> >    until we have an encoder than can actually do mid-stream
> >    resolution changes.
> >
> >    If sizeimage of the OUTPUT is too small for the CAPTURE
> >    resolution and V4L2_EVENT_SOURCE_CHANGE is not supported,
> >    then the second STREAMON (either CAPTURE or OUTPUT) will
> >    return -ENOMEM since there is not enough memory to do the
> >    encode.
>
> You seem confident that we will know immediately if it's too small. But
> what I remember is that HW has an interrupt for this, allowing
> userspace to allocate a larger buffer and resume.
>
> Should we make the capture queue independent of the streaming state, so
> that we can streamoff/reqbufs/.../streamon to resume from an ENOMEM
> error ? And shouldn't ENOMEM be returned by the following capture DQBUF
> when such an interrupt is raised ?
>

The idea was that stopping the CAPTURE queue would reset the encoder,
i.e. start encoding a new, independent stream after the streaming
starts again. Still, given that one would normally need to reallocate
the buffers on some significant stream parameter change, that would
normally require emitting all the relevant headers anyway, so it
probably doesn't break anything?

Best regards,
Tomasz

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Nicolas Dufresne]

[-- Attachment #1: Type: text/plain, Size: 5222 bytes --]

Le mercredi 03 juillet 2019 à 18:04 +0900, Tomasz Figa a écrit :
> On Wed, Jun 5, 2019 at 12:19 AM Nicolas Dufresne <nicolas@ndufresne.ca> wrote:
> > Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> > > Since Thomasz was very busy with other things, I've taken over this
> > > patch series. This v4 includes his draft changes and additional changes
> > > from me.
> > > 
> > > This series attempts to add the documentation of what was discussed
> > > during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
> > > later Embedded Linux Conference Europe 2014 in Düsseldorf and then
> > > eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
> > > video team (but mostly in a cosmetic way or making the document more
> > > precise), during the several years of Chrome OS using the APIs in
> > > production.
> > > 
> > > Note that most, if not all, of the API is already implemented in
> > > existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
> > > this series is just to formalize what we already have.
> > > 
> > > Thanks everyone for the huge amount of useful comments to previous
> > > versions of this series. Much of the credits should go to Pawel Osciak
> > > too, for writing most of the original text of the initial RFC.
> > > 
> > > This v4 incorporates all known comments (let me know if I missed
> > > something!) and should be complete for the decoder.
> > > 
> > > For the encoder there are two remaining TODOs for the API:
> > > 
> > > 1) Setting the frame rate so bitrate control can make sense, since
> > >    they need to know this information.
> > > 
> > >    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
> > >    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
> > >    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
> > >    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
> > >    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.
> > 
> > I agree, as long as it's documented. I can imagine how this could be
> > confusing for new users.
> > 
> > > 2) Interactions between OUTPUT and CAPTURE formats.
> > > 
> > >    The main problem is what to do if the capture sizeimage is too small
> > >    for the OUTPUT resolution when streaming starts.
> > > 
> > >    Proposal: width and height of S_FMT(OUTPUT) are used to
> > >    calculate a minimum sizeimage (app may request more). This is
> > >    driver-specific.
> > > 
> > >    V4L2_FMT_FLAG_FIXED_RESOLUTION is always set for codec formats
> > >    for the encoder (i.e. we don't support mid-stream resolution
> > >    changes for now) and V4L2_EVENT_SOURCE_CHANGE is not
> > >    supported. See https://patchwork.linuxtv.org/patch/56478/ for
> > >    the patch adding this flag.
> > > 
> > >    Of course, if we start to support mid-stream resolution
> > >    changes (or other changes that require a source change event),
> > >    then this flag should be dropped by the encoder driver and
> > >    documentation on how to handle the source change event should
> > >    be documented in the encoder spec. I prefer to postpone this
> > >    until we have an encoder than can actually do mid-stream
> > >    resolution changes.
> > > 
> > >    If sizeimage of the OUTPUT is too small for the CAPTURE
> > >    resolution and V4L2_EVENT_SOURCE_CHANGE is not supported,
> > >    then the second STREAMON (either CAPTURE or OUTPUT) will
> > >    return -ENOMEM since there is not enough memory to do the
> > >    encode.
> > 
> > You seem confident that we will know immediately if it's too small. But
> > what I remember is that HW has an interrupt for this, allowing
> > userspace to allocate a larger buffer and resume.
> > 
> > Should we make the capture queue independent of the streaming state, so
> > that we can streamoff/reqbufs/.../streamon to resume from an ENOMEM
> > error ? And shouldn't ENOMEM be returned by the following capture DQBUF
> > when such an interrupt is raised ?
> > 
> 
> The idea was that stopping the CAPTURE queue would reset the encoder,
> i.e. start encoding a new, independent stream after the streaming
> starts again. Still, given that one would normally need to reallocate
> the buffers on some significant stream parameter change, that would
> normally require emitting all the relevant headers anyway, so it
> probably doesn't break anything?

The capture buffer size is a prediction, so even without any parameters
changes, the size could become insufficient. On the other hand, we have
managed to predict quite well so far in many applications.

Note, I didn't remember that encoder CAPTURE queue streamoff was the
one triggering the reset. In GStreamer, I always streamoff both, so I
never had to think about this. One thing is clear though, it will be
really hard to extend later with this hard relationship between
allocation, streaming state and encoder state. I'm sure we can survive
this, there is probably plenty of workaround, including spreading
encoded data across multiple buffer as Hans suggested.

> 
> Best regards,
> Tomasz

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Nicolas Dufresne]

[-- Attachment #1: Type: text/plain, Size: 8206 bytes --]

Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> Since Thomasz was very busy with other things, I've taken over this
> patch series. This v4 includes his draft changes and additional changes
> from me.
> 
> This series attempts to add the documentation of what was discussed
> during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
> later Embedded Linux Conference Europe 2014 in Düsseldorf and then
> eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
> video team (but mostly in a cosmetic way or making the document more
> precise), during the several years of Chrome OS using the APIs in
> production.
> 
> Note that most, if not all, of the API is already implemented in
> existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
> this series is just to formalize what we already have.
> 
> Thanks everyone for the huge amount of useful comments to previous
> versions of this series. Much of the credits should go to Pawel Osciak
> too, for writing most of the original text of the initial RFC.
> 
> This v4 incorporates all known comments (let me know if I missed
> something!) and should be complete for the decoder.
> 
> For the encoder there are two remaining TODOs for the API:
> 
> 1) Setting the frame rate so bitrate control can make sense, since
>    they need to know this information.
> 
>    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
>    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
>    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
>    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
>    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.

Is ENUM_FRAMEINTERVALS really required ? This will be a hint to the
encoder, so that the encoder round to it's internal precision does not
seem very important.

> 
> 2) Interactions between OUTPUT and CAPTURE formats.
> 
>    The main problem is what to do if the capture sizeimage is too small
>    for the OUTPUT resolution when streaming starts.
> 
>    Proposal: width and height of S_FMT(OUTPUT) are used to
>    calculate a minimum sizeimage (app may request more). This is
>    driver-specific.
> 
>    V4L2_FMT_FLAG_FIXED_RESOLUTION is always set for codec formats
>    for the encoder (i.e. we don't support mid-stream resolution
>    changes for now) and V4L2_EVENT_SOURCE_CHANGE is not
>    supported. See https://patchwork.linuxtv.org/patch/56478/ for
>    the patch adding this flag.
> 
>    Of course, if we start to support mid-stream resolution
>    changes (or other changes that require a source change event),
>    then this flag should be dropped by the encoder driver and
>    documentation on how to handle the source change event should
>    be documented in the encoder spec. I prefer to postpone this
>    until we have an encoder than can actually do mid-stream
>    resolution changes.

For H264, mid-stream changes would make sense for the case we'd like
the statefull encoder to emit multiple PPS at start, so then the switch
would simply change the PPS index. The problem seems to be how do we
expose "multiple" resolution in our interface ? As there is currently
no solution to this, I would not see much use for having this supported
at the moment.

> 
>    If sizeimage of the OUTPUT is too small for the CAPTURE
>    resolution and V4L2_EVENT_SOURCE_CHANGE is not supported,
>    then the second STREAMON (either CAPTURE or OUTPUT) will
>    return -ENOMEM since there is not enough memory to do the
>    encode.
> 
>    If V4L2_FMT_FLAG_FIXED_RESOLUTION is set (i.e. that should
>    be the case for all current encoders), then any bitrate controls
>    will be limited in range to what the current state (CAPTURE and
>    OUTPUT formats and frame rate) supports.
> 
> Comments regarding these two encoder proposals are welcome!
> 
> Regards,
> 
> 	Hans
> 
> Changes since v3:
> 
> - Lots of stylistic fixes and fixing typos/grammar/etc.
> 
> Decoder:
> 
> - width/height for S_FMT(OUTPUT):
> 
>   Expects that the output width and height is always a valid
>   resolution (i.e. never 0x0), and G/S/TRY_FMT and REQBUFS will use that
>   instead of returning an error. Note that this resolution is a placeholder
>   until the actual resolution is parsed from the stream.
> 
> - Dropped step 3 (Query the minimum number of buffers required for the CAPTURE
>   queue via VIDIOC_G_CTRL().) in the Capture Setup section. It seems to be
>   a left-over from earlier versions. The same information is also in Step 10,
>   so no need to have this in two places.
> 
> - Added step 5 in the Capture Setup section: set COMPOSE rectangle if needed.
> 
> - VIDIO_DECODER_CMD: document EBUSY return while draining the queue.
> 
> Encoder:
> 
> - width/height for S_FMT(CAPTURE): The width/height for the CAPTURE format
>   are marked as read-only and are based on the encoders current state such
>   as the OUTPUT format.
> 
> - Drop TGT_COMPOSE support in the encoder: there are currently
>   no encoders that can do composing/scaling.
> 
> - Document corner cases in the Drain sequence
> 
> - Document error handling.
> 
> - VIDIO_ENCODER_CMD: document EBUSY return while draining the queue.
> 
> Changes since v2:
> (https://lore.kernel.org/patchwork/cover/1002474/)
> Decoder:
>  - Specified that the initial source change event is signaled
>    regardless of whether the client-set format matches the
>    stream format.
>  - Dropped V4L2_CID_MIN_BUFFERS_FOR_OUTPUT since it's meaningless
>    for the bitstream input buffers of decoders.
>  - Explicitly stated that VIDIOC_REQBUFS is not allowed on CAPTURE
>    if the stream information is not available.
>  - Described decode error handling.
>  - Mentioned that timestamps can be observed after a seek to
>    determine whether the CAPTURE buffers originated from before
>    or after the seek.
>  - Explicitly stated that after a pair of V4L2_DEC_CMD_STOP and
>    V4L2_DEC_CMD_START, the decoder is not reset and preserves
>    all the state.
> 
> Encoder:
>  - Specified that width and height of CAPTURE format are ignored
>    and always zero.
>  - Explicitly noted the common use case for the CROP target with
>    macroblock-unaligned video resolutions.
>  - Added a reference to Request API.
>  - Dropped V4L2_CID_MIN_BUFFERS_FOR_CAPTURE since it's meaningless
>    for the bitstream output buffers of encoders.
>  - Explicitly stated that after a pair of V4L2_ENC_CMD_STOP and
>    V4L2_ENC_CMD_START, the encoder is not reset and preserves
>    all the state.
> 
> General:
>  - Dropped format enumeration from "Initialization", since it's already
>    a part of "Querying capabilities".
>  - Many spelling, grammar, stylistic, etc. changes.
>  - Changed the style of note blocks.
>  - Rebased onto Hans' documentation cleanup series.
>    (https://patchwork.kernel.org/cover/10775407/
>     https://patchwork.kernel.org/patch/10776737/)
>  - Moved the interfaces under the "Video Memory-To-Memory Interface"
>    section.
> 
> For changes since v1 see the v2:
> https://lore.kernel.org/patchwork/cover/1002474/
> 
> For changes since RFC see the v1:
> https://patchwork.kernel.org/cover/10542207/
> 
> Tomasz Figa (2):
>   media: docs-rst: Document memory-to-memory video decoder interface
>   media: docs-rst: Document memory-to-memory video encoder interface
> 
>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
>  Documentation/media/uapi/v4l/dev-encoder.rst  |  608 +++++++++
>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    9 +-
>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |   10 +
>  Documentation/media/uapi/v4l/v4l2.rst         |   12 +-
>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
>  .../media/uapi/v4l/vidioc-encoder-cmd.rst     |   51 +-
>  7 files changed, 1779 insertions(+), 36 deletions(-)
>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>  create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst
> 

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Hans Verkuil]

On 6/10/19 5:57 PM, Nicolas Dufresne wrote:
> Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
>> Since Thomasz was very busy with other things, I've taken over this
>> patch series. This v4 includes his draft changes and additional changes
>> from me.
>>
>> This series attempts to add the documentation of what was discussed
>> during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
>> later Embedded Linux Conference Europe 2014 in Düsseldorf and then
>> eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
>> video team (but mostly in a cosmetic way or making the document more
>> precise), during the several years of Chrome OS using the APIs in
>> production.
>>
>> Note that most, if not all, of the API is already implemented in
>> existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
>> this series is just to formalize what we already have.
>>
>> Thanks everyone for the huge amount of useful comments to previous
>> versions of this series. Much of the credits should go to Pawel Osciak
>> too, for writing most of the original text of the initial RFC.
>>
>> This v4 incorporates all known comments (let me know if I missed
>> something!) and should be complete for the decoder.
>>
>> For the encoder there are two remaining TODOs for the API:
>>
>> 1) Setting the frame rate so bitrate control can make sense, since
>>    they need to know this information.
>>
>>    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
>>    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
>>    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
>>    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
>>    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.
> 
> Is ENUM_FRAMEINTERVALS really required ? This will be a hint to the
> encoder, so that the encoder round to it's internal precision does not
> seem very important.

I don't like this proposal. Especially the use of S_PARM (I *hate* that ioctl).
I think the frame period should be a control with a min/max range, like
any other control.

FRAMEINTERVALS really refers to the rate at which frames arrive when
capturing, and that's not quite what is happening in an encoder.

For now I want to concentrate on the decoder spec, and I'll come back to
this later.

> 
>>
>> 2) Interactions between OUTPUT and CAPTURE formats.
>>
>>    The main problem is what to do if the capture sizeimage is too small
>>    for the OUTPUT resolution when streaming starts.
>>
>>    Proposal: width and height of S_FMT(OUTPUT) are used to
>>    calculate a minimum sizeimage (app may request more). This is
>>    driver-specific.
>>
>>    V4L2_FMT_FLAG_FIXED_RESOLUTION is always set for codec formats
>>    for the encoder (i.e. we don't support mid-stream resolution
>>    changes for now) and V4L2_EVENT_SOURCE_CHANGE is not
>>    supported. See https://patchwork.linuxtv.org/patch/56478/ for
>>    the patch adding this flag.
>>
>>    Of course, if we start to support mid-stream resolution
>>    changes (or other changes that require a source change event),
>>    then this flag should be dropped by the encoder driver and
>>    documentation on how to handle the source change event should
>>    be documented in the encoder spec. I prefer to postpone this
>>    until we have an encoder than can actually do mid-stream
>>    resolution changes.
> 
> For H264, mid-stream changes would make sense for the case we'd like
> the statefull encoder to emit multiple PPS at start, so then the switch
> would simply change the PPS index. The problem seems to be how do we
> expose "multiple" resolution in our interface ? As there is currently
> no solution to this, I would not see much use for having this supported
> at the moment.

I agree. That's why I want to postpone that part.

> 
>>
>>    If sizeimage of the OUTPUT is too small for the CAPTURE
>>    resolution and V4L2_EVENT_SOURCE_CHANGE is not supported,
>>    then the second STREAMON (either CAPTURE or OUTPUT) will
>>    return -ENOMEM since there is not enough memory to do the
>>    encode.
>>
>>    If V4L2_FMT_FLAG_FIXED_RESOLUTION is set (i.e. that should
>>    be the case for all current encoders), then any bitrate controls
>>    will be limited in range to what the current state (CAPTURE and
>>    OUTPUT formats and frame rate) supports.

Note that this flag will be inverted: V4L2_FMT_FLAG_DYN_RESOLUTION.
So this text is out of date in that regard.

Regards,

	Hans

>>
>> Comments regarding these two encoder proposals are welcome!
>>
>> Regards,
>>
>> 	Hans
>>
>> Changes since v3:
>>
>> - Lots of stylistic fixes and fixing typos/grammar/etc.
>>
>> Decoder:
>>
>> - width/height for S_FMT(OUTPUT):
>>
>>   Expects that the output width and height is always a valid
>>   resolution (i.e. never 0x0), and G/S/TRY_FMT and REQBUFS will use that
>>   instead of returning an error. Note that this resolution is a placeholder
>>   until the actual resolution is parsed from the stream.
>>
>> - Dropped step 3 (Query the minimum number of buffers required for the CAPTURE
>>   queue via VIDIOC_G_CTRL().) in the Capture Setup section. It seems to be
>>   a left-over from earlier versions. The same information is also in Step 10,
>>   so no need to have this in two places.
>>
>> - Added step 5 in the Capture Setup section: set COMPOSE rectangle if needed.
>>
>> - VIDIO_DECODER_CMD: document EBUSY return while draining the queue.
>>
>> Encoder:
>>
>> - width/height for S_FMT(CAPTURE): The width/height for the CAPTURE format
>>   are marked as read-only and are based on the encoders current state such
>>   as the OUTPUT format.
>>
>> - Drop TGT_COMPOSE support in the encoder: there are currently
>>   no encoders that can do composing/scaling.
>>
>> - Document corner cases in the Drain sequence
>>
>> - Document error handling.
>>
>> - VIDIO_ENCODER_CMD: document EBUSY return while draining the queue.
>>
>> Changes since v2:
>> (https://lore.kernel.org/patchwork/cover/1002474/)
>> Decoder:
>>  - Specified that the initial source change event is signaled
>>    regardless of whether the client-set format matches the
>>    stream format.
>>  - Dropped V4L2_CID_MIN_BUFFERS_FOR_OUTPUT since it's meaningless
>>    for the bitstream input buffers of decoders.
>>  - Explicitly stated that VIDIOC_REQBUFS is not allowed on CAPTURE
>>    if the stream information is not available.
>>  - Described decode error handling.
>>  - Mentioned that timestamps can be observed after a seek to
>>    determine whether the CAPTURE buffers originated from before
>>    or after the seek.
>>  - Explicitly stated that after a pair of V4L2_DEC_CMD_STOP and
>>    V4L2_DEC_CMD_START, the decoder is not reset and preserves
>>    all the state.
>>
>> Encoder:
>>  - Specified that width and height of CAPTURE format are ignored
>>    and always zero.
>>  - Explicitly noted the common use case for the CROP target with
>>    macroblock-unaligned video resolutions.
>>  - Added a reference to Request API.
>>  - Dropped V4L2_CID_MIN_BUFFERS_FOR_CAPTURE since it's meaningless
>>    for the bitstream output buffers of encoders.
>>  - Explicitly stated that after a pair of V4L2_ENC_CMD_STOP and
>>    V4L2_ENC_CMD_START, the encoder is not reset and preserves
>>    all the state.
>>
>> General:
>>  - Dropped format enumeration from "Initialization", since it's already
>>    a part of "Querying capabilities".
>>  - Many spelling, grammar, stylistic, etc. changes.
>>  - Changed the style of note blocks.
>>  - Rebased onto Hans' documentation cleanup series.
>>    (https://patchwork.kernel.org/cover/10775407/
>>     https://patchwork.kernel.org/patch/10776737/)
>>  - Moved the interfaces under the "Video Memory-To-Memory Interface"
>>    section.
>>
>> For changes since v1 see the v2:
>> https://lore.kernel.org/patchwork/cover/1002474/
>>
>> For changes since RFC see the v1:
>> https://patchwork.kernel.org/cover/10542207/
>>
>> Tomasz Figa (2):
>>   media: docs-rst: Document memory-to-memory video decoder interface
>>   media: docs-rst: Document memory-to-memory video encoder interface
>>
>>  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
>>  Documentation/media/uapi/v4l/dev-encoder.rst  |  608 +++++++++
>>  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    9 +-
>>  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |   10 +
>>  Documentation/media/uapi/v4l/v4l2.rst         |   12 +-
>>  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
>>  .../media/uapi/v4l/vidioc-encoder-cmd.rst     |   51 +-
>>  7 files changed, 1779 insertions(+), 36 deletions(-)
>>  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>>  create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst
>>

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Nicolas Dufresne]

Le mardi 11 juin 2019 à 10:35 +0200, Hans Verkuil a écrit :
> On 6/10/19 5:57 PM, Nicolas Dufresne wrote:
> > Le lundi 03 juin 2019 à 13:28 +0200, Hans Verkuil a écrit :
> > > Since Thomasz was very busy with other things, I've taken over this
> > > patch series. This v4 includes his draft changes and additional changes
> > > from me.
> > > 
> > > This series attempts to add the documentation of what was discussed
> > > during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
> > > later Embedded Linux Conference Europe 2014 in Düsseldorf and then
> > > eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
> > > video team (but mostly in a cosmetic way or making the document more
> > > precise), during the several years of Chrome OS using the APIs in
> > > production.
> > > 
> > > Note that most, if not all, of the API is already implemented in
> > > existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
> > > this series is just to formalize what we already have.
> > > 
> > > Thanks everyone for the huge amount of useful comments to previous
> > > versions of this series. Much of the credits should go to Pawel Osciak
> > > too, for writing most of the original text of the initial RFC.
> > > 
> > > This v4 incorporates all known comments (let me know if I missed
> > > something!) and should be complete for the decoder.
> > > 
> > > For the encoder there are two remaining TODOs for the API:
> > > 
> > > 1) Setting the frame rate so bitrate control can make sense, since
> > >    they need to know this information.
> > > 
> > >    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
> > >    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
> > >    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
> > >    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
> > >    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.
> > 
> > Is ENUM_FRAMEINTERVALS really required ? This will be a hint to the
> > encoder, so that the encoder round to it's internal precision does not
> > seem very important.
> 
> I don't like this proposal. Especially the use of S_PARM (I *hate* that ioctl).
> I think the frame period should be a control with a min/max range, like
> any other control.
> 
> FRAMEINTERVALS really refers to the rate at which frames arrive when
> capturing, and that's not quite what is happening in an encoder.

Only side is that this is exactly what happens when doing live encoding
(to site GStreamer):

   v4l2src ! v4l2encoder ! ...

The frameinterval is exactly what the V4L2 capture device reports.
Though, a lot of encoder used for RTP transcoding takes a per frame
duration as input, as RTP does not always expose the framerate (aka
frame duration). Or the other way around is that the frameinterval is
calculates and updated periodically (S_PARM do have this advantage that
you are suppose to be able to change that while streaming, no idea if
that works in practice). I do not like the ioctl() though. This could
have been a control and could be called framerate to match what the
rest of the world uses.

> 
> For now I want to concentrate on the decoder spec, and I'll come back to
> this later.

Ok.

> 
> > > 2) Interactions between OUTPUT and CAPTURE formats.
> > > 
> > >    The main problem is what to do if the capture sizeimage is too small
> > >    for the OUTPUT resolution when streaming starts.
> > > 
> > >    Proposal: width and height of S_FMT(OUTPUT) are used to
> > >    calculate a minimum sizeimage (app may request more). This is
> > >    driver-specific.
> > > 
> > >    V4L2_FMT_FLAG_FIXED_RESOLUTION is always set for codec formats
> > >    for the encoder (i.e. we don't support mid-stream resolution
> > >    changes for now) and V4L2_EVENT_SOURCE_CHANGE is not
> > >    supported. See https://patchwork.linuxtv.org/patch/56478/ for
> > >    the patch adding this flag.
> > > 
> > >    Of course, if we start to support mid-stream resolution
> > >    changes (or other changes that require a source change event),
> > >    then this flag should be dropped by the encoder driver and
> > >    documentation on how to handle the source change event should
> > >    be documented in the encoder spec. I prefer to postpone this
> > >    until we have an encoder than can actually do mid-stream
> > >    resolution changes.
> > 
> > For H264, mid-stream changes would make sense for the case we'd like
> > the statefull encoder to emit multiple PPS at start, so then the switch
> > would simply change the PPS index. The problem seems to be how do we
> > expose "multiple" resolution in our interface ? As there is currently
> > no solution to this, I would not see much use for having this supported
> > at the moment.
> 
> I agree. That's why I want to postpone that part.
> 
> > >    If sizeimage of the OUTPUT is too small for the CAPTURE
> > >    resolution and V4L2_EVENT_SOURCE_CHANGE is not supported,
> > >    then the second STREAMON (either CAPTURE or OUTPUT) will
> > >    return -ENOMEM since there is not enough memory to do the
> > >    encode.
> > > 
> > >    If V4L2_FMT_FLAG_FIXED_RESOLUTION is set (i.e. that should
> > >    be the case for all current encoders), then any bitrate controls
> > >    will be limited in range to what the current state (CAPTURE and
> > >    OUTPUT formats and frame rate) supports.
> 
> Note that this flag will be inverted: V4L2_FMT_FLAG_DYN_RESOLUTION.
> So this text is out of date in that regard.
> 
> Regards,
> 
> 	Hans
> 
> > > Comments regarding these two encoder proposals are welcome!
> > > 
> > > Regards,
> > > 
> > > 	Hans
> > > 
> > > Changes since v3:
> > > 
> > > - Lots of stylistic fixes and fixing typos/grammar/etc.
> > > 
> > > Decoder:
> > > 
> > > - width/height for S_FMT(OUTPUT):
> > > 
> > >   Expects that the output width and height is always a valid
> > >   resolution (i.e. never 0x0), and G/S/TRY_FMT and REQBUFS will use that
> > >   instead of returning an error. Note that this resolution is a placeholder
> > >   until the actual resolution is parsed from the stream.
> > > 
> > > - Dropped step 3 (Query the minimum number of buffers required for the CAPTURE
> > >   queue via VIDIOC_G_CTRL().) in the Capture Setup section. It seems to be
> > >   a left-over from earlier versions. The same information is also in Step 10,
> > >   so no need to have this in two places.
> > > 
> > > - Added step 5 in the Capture Setup section: set COMPOSE rectangle if needed.
> > > 
> > > - VIDIO_DECODER_CMD: document EBUSY return while draining the queue.
> > > 
> > > Encoder:
> > > 
> > > - width/height for S_FMT(CAPTURE): The width/height for the CAPTURE format
> > >   are marked as read-only and are based on the encoders current state such
> > >   as the OUTPUT format.
> > > 
> > > - Drop TGT_COMPOSE support in the encoder: there are currently
> > >   no encoders that can do composing/scaling.
> > > 
> > > - Document corner cases in the Drain sequence
> > > 
> > > - Document error handling.
> > > 
> > > - VIDIO_ENCODER_CMD: document EBUSY return while draining the queue.
> > > 
> > > Changes since v2:
> > > (https://lore.kernel.org/patchwork/cover/1002474/)
> > > Decoder:
> > >  - Specified that the initial source change event is signaled
> > >    regardless of whether the client-set format matches the
> > >    stream format.
> > >  - Dropped V4L2_CID_MIN_BUFFERS_FOR_OUTPUT since it's meaningless
> > >    for the bitstream input buffers of decoders.
> > >  - Explicitly stated that VIDIOC_REQBUFS is not allowed on CAPTURE
> > >    if the stream information is not available.
> > >  - Described decode error handling.
> > >  - Mentioned that timestamps can be observed after a seek to
> > >    determine whether the CAPTURE buffers originated from before
> > >    or after the seek.
> > >  - Explicitly stated that after a pair of V4L2_DEC_CMD_STOP and
> > >    V4L2_DEC_CMD_START, the decoder is not reset and preserves
> > >    all the state.
> > > 
> > > Encoder:
> > >  - Specified that width and height of CAPTURE format are ignored
> > >    and always zero.
> > >  - Explicitly noted the common use case for the CROP target with
> > >    macroblock-unaligned video resolutions.
> > >  - Added a reference to Request API.
> > >  - Dropped V4L2_CID_MIN_BUFFERS_FOR_CAPTURE since it's meaningless
> > >    for the bitstream output buffers of encoders.
> > >  - Explicitly stated that after a pair of V4L2_ENC_CMD_STOP and
> > >    V4L2_ENC_CMD_START, the encoder is not reset and preserves
> > >    all the state.
> > > 
> > > General:
> > >  - Dropped format enumeration from "Initialization", since it's already
> > >    a part of "Querying capabilities".
> > >  - Many spelling, grammar, stylistic, etc. changes.
> > >  - Changed the style of note blocks.
> > >  - Rebased onto Hans' documentation cleanup series.
> > >    (https://patchwork.kernel.org/cover/10775407/
> > >     https://patchwork.kernel.org/patch/10776737/)
> > >  - Moved the interfaces under the "Video Memory-To-Memory Interface"
> > >    section.
> > > 
> > > For changes since v1 see the v2:
> > > https://lore.kernel.org/patchwork/cover/1002474/
> > > 
> > > For changes since RFC see the v1:
> > > https://patchwork.kernel.org/cover/10542207/
> > > 
> > > Tomasz Figa (2):
> > >   media: docs-rst: Document memory-to-memory video decoder interface
> > >   media: docs-rst: Document memory-to-memory video encoder interface
> > > 
> > >  Documentation/media/uapi/v4l/dev-decoder.rst  | 1084 +++++++++++++++++
> > >  Documentation/media/uapi/v4l/dev-encoder.rst  |  608 +++++++++
> > >  Documentation/media/uapi/v4l/dev-mem2mem.rst  |    9 +-
> > >  Documentation/media/uapi/v4l/pixfmt-v4l2.rst  |   10 +
> > >  Documentation/media/uapi/v4l/v4l2.rst         |   12 +-
> > >  .../media/uapi/v4l/vidioc-decoder-cmd.rst     |   41 +-
> > >  .../media/uapi/v4l/vidioc-encoder-cmd.rst     |   51 +-
> > >  7 files changed, 1779 insertions(+), 36 deletions(-)
> > >  create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> > >  create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst
> > > 

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Hans Verkuil]

On 6/3/19 1:28 PM, Hans Verkuil wrote:
> Since Tomasz was very busy with other things, I've taken over this
> patch series. This v4 includes his draft changes and additional changes
> from me.
> 
> This series attempts to add the documentation of what was discussed
> during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
> later Embedded Linux Conference Europe 2014 in Düsseldorf and then
> eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
> video team (but mostly in a cosmetic way or making the document more
> precise), during the several years of Chrome OS using the APIs in
> production.
> 
> Note that most, if not all, of the API is already implemented in
> existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
> this series is just to formalize what we already have.
> 
> Thanks everyone for the huge amount of useful comments to previous
> versions of this series. Much of the credits should go to Pawel Osciak
> too, for writing most of the original text of the initial RFC.
> 
> This v4 incorporates all known comments (let me know if I missed
> something!) and should be complete for the decoder.
> 
> For the encoder there are two remaining TODOs for the API:
> 
> 1) Setting the frame rate so bitrate control can make sense, since
>    they need to know this information.
> 
>    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
>    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
>    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
>    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
>    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.

Alternative proposal:

1) Add support for fractions (struct v4l2_fract) as a control type:
   V4L2_CTRL_TYPE_FRACT.

2) Add a new V4L2_CID_MPEG_FRAME_INTERVAL control.

Encoders shall support this control.

3) For backwards compatibility reasons encoder drivers still have to
support G/S_PARM, but this can now be implemented by standard helpers
that query this control. Drivers also have to implement ENUM_FRAMEINTERVALS.
If the range of intervals is always the same regardless of the frame size,
then a helper can be used that queries the min/max/step of the control, but
if it is dependent on the frame size, then it has to be implemented in the
driver itself.

I'm sticking to frame intervals instead of frame rates for the simple reason
that that's what V4L2 has used since the beginning. I think it is too confusing
to change this to a frame rate. This is just my opinion, though.

I also chose to make this a codec control, not a generic user control: this
value together with the bit rate control(s) determine the compression size,
it does not determine the actual time it takes for the encoder to compress
the raw frames. Hence it is really not the same thing as the frame interval
of a video capture device. If we want to use a control for that as well in
the future as a replacement for G/S_PARM, then that should be a new control.
And we would like need per-pad controls as well in order to implement that.
Which is a lot more work.

Regards,

	Hans

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Nicolas Dufresne]

Le jeudi 13 juin 2019 à 08:48 +0200, Hans Verkuil a écrit :
> On 6/3/19 1:28 PM, Hans Verkuil wrote:
> > Since Tomasz was very busy with other things, I've taken over this
> > patch series. This v4 includes his draft changes and additional changes
> > from me.
> > 
> > This series attempts to add the documentation of what was discussed
> > during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
> > later Embedded Linux Conference Europe 2014 in Düsseldorf and then
> > eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
> > video team (but mostly in a cosmetic way or making the document more
> > precise), during the several years of Chrome OS using the APIs in
> > production.
> > 
> > Note that most, if not all, of the API is already implemented in
> > existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
> > this series is just to formalize what we already have.
> > 
> > Thanks everyone for the huge amount of useful comments to previous
> > versions of this series. Much of the credits should go to Pawel Osciak
> > too, for writing most of the original text of the initial RFC.
> > 
> > This v4 incorporates all known comments (let me know if I missed
> > something!) and should be complete for the decoder.
> > 
> > For the encoder there are two remaining TODOs for the API:
> > 
> > 1) Setting the frame rate so bitrate control can make sense, since
> >    they need to know this information.
> > 
> >    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
> >    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
> >    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
> >    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
> >    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.
> 
> Alternative proposal:
> 
> 1) Add support for fractions (struct v4l2_fract) as a control type:
>    V4L2_CTRL_TYPE_FRACT.
> 
> 2) Add a new V4L2_CID_MPEG_FRAME_INTERVAL control.

Is the MPEG namespace historical ? That might be confusing for users.

> 
> Encoders shall support this control.
> 
> 3) For backwards compatibility reasons encoder drivers still have to
> support G/S_PARM, but this can now be implemented by standard helpers
> that query this control. Drivers also have to implement ENUM_FRAMEINTERVALS.

That's won't be very friendly for UI generator like qv4l2. Support for
v4l2_fract as control should include a way to describe the supported
values of that control the usual way I think.

Also, long term, it would be nice to have two sets of frame rates. The
one that the HW can handle "real-time" and the one that can be used for
bitrate calculation. So staying away from ENUM_FRAMEINTERVALS for
bitrate configuration would be nicer.

> If the range of intervals is always the same regardless of the frame size,
> then a helper can be used that queries the min/max/step of the control, but
> if it is dependent on the frame size, then it has to be implemented in the
> driver itself.
> 
> I'm sticking to frame intervals instead of frame rates for the simple reason
> that that's what V4L2 has used since the beginning. I think it is too confusing
> to change this to a frame rate. This is just my opinion, though.

I suggested frame rate since this is what I saw implemented by HW
registers (if you think it's worth it, I can try and make a list).
Also, frame-interval steps are not compatible with frame-rate steps
(something that was raised through a venus driver bug) last year. Even
v4l2-ctl was displaying that in a very confusing way. Something as
simple as 1 to 30 fps cannot be exposed through ENU_FRAMEINTERVALS. You
are forced to expose the full fractional range of interval, from 1/30
to 1/1. For Venus it was not that much of a trouble, since its stores a
framerate as Q16..

> 
> I also chose to make this a codec control, not a generic user control: this
> value together with the bit rate control(s) determine the compression size,
> it does not determine the actual time it takes for the encoder to compress
> the raw frames. Hence it is really not the same thing as the frame interval

That's a good point.

> of a video capture device. If we want to use a control for that as well in
> the future as a replacement for G/S_PARM, then that should be a new control.
> And we would like need per-pad controls as well in order to implement that.
> Which is a lot more work.
> 
> Regards,
> 
> 	Hans

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Hans Verkuil]

On 6/14/19 3:09 AM, Nicolas Dufresne wrote:
> Le jeudi 13 juin 2019 à 08:48 +0200, Hans Verkuil a écrit :
>> On 6/3/19 1:28 PM, Hans Verkuil wrote:
>>> Since Tomasz was very busy with other things, I've taken over this
>>> patch series. This v4 includes his draft changes and additional changes
>>> from me.
>>>
>>> This series attempts to add the documentation of what was discussed
>>> during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
>>> later Embedded Linux Conference Europe 2014 in Düsseldorf and then
>>> eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
>>> video team (but mostly in a cosmetic way or making the document more
>>> precise), during the several years of Chrome OS using the APIs in
>>> production.
>>>
>>> Note that most, if not all, of the API is already implemented in
>>> existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
>>> this series is just to formalize what we already have.
>>>
>>> Thanks everyone for the huge amount of useful comments to previous
>>> versions of this series. Much of the credits should go to Pawel Osciak
>>> too, for writing most of the original text of the initial RFC.
>>>
>>> This v4 incorporates all known comments (let me know if I missed
>>> something!) and should be complete for the decoder.
>>>
>>> For the encoder there are two remaining TODOs for the API:
>>>
>>> 1) Setting the frame rate so bitrate control can make sense, since
>>>    they need to know this information.
>>>
>>>    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
>>>    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
>>>    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
>>>    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
>>>    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.
>>
>> Alternative proposal:
>>
>> 1) Add support for fractions (struct v4l2_fract) as a control type:
>>    V4L2_CTRL_TYPE_FRACT.
>>
>> 2) Add a new V4L2_CID_MPEG_FRAME_INTERVAL control.
> 
> Is the MPEG namespace historical ? That might be confusing for users.

Yes, it's historical. I have toyed with the idea of renaming all the
defines to something like V4L2_CID_CODEC_... (keeping the old defines, of
course), but I'm not sure it is worth it.

> 
>>
>> Encoders shall support this control.
>>
>> 3) For backwards compatibility reasons encoder drivers still have to
>> support G/S_PARM, but this can now be implemented by standard helpers
>> that query this control. Drivers also have to implement ENUM_FRAMEINTERVALS.
> 
> That's won't be very friendly for UI generator like qv4l2. Support for
> v4l2_fract as control should include a way to describe the supported
> values of that control the usual way I think.

Such a control will definitely have the usual min/max/step/default control
values.

> Also, long term, it would be nice to have two sets of frame rates. The
> one that the HW can handle "real-time" and the one that can be used for
> bitrate calculation. So staying away from ENUM_FRAMEINTERVALS for
> bitrate configuration would be nicer.

I'm not sure if that's feasible in practice, although the idea is nice.
The 'real-time' framerate will likely depend to a huge extent on the
frequency of various internal clocks and the content of the bitstream.

I suspect it will be very hard if not impossible to report realistic
ENUM_FRAMEINTERVAL values for codecs.

> 
>> If the range of intervals is always the same regardless of the frame size,
>> then a helper can be used that queries the min/max/step of the control, but
>> if it is dependent on the frame size, then it has to be implemented in the
>> driver itself.
>>
>> I'm sticking to frame intervals instead of frame rates for the simple reason
>> that that's what V4L2 has used since the beginning. I think it is too confusing
>> to change this to a frame rate. This is just my opinion, though.
> 
> I suggested frame rate since this is what I saw implemented by HW
> registers (if you think it's worth it, I can try and make a list).
> Also, frame-interval steps are not compatible with frame-rate steps
> (something that was raised through a venus driver bug) last year. Even
> v4l2-ctl was displaying that in a very confusing way. Something as
> simple as 1 to 30 fps cannot be exposed through ENU_FRAMEINTERVALS. You
> are forced to expose the full fractional range of interval, from 1/30
> to 1/1. For Venus it was not that much of a trouble, since its stores a
> framerate as Q16..

Since this is used for bitrate calculations, and not for determining the
exact framerate, I'm not sure it matters all that much in this particular
case. Since you still need to implement G/S_PARM in drivers for backwards
compatibility reasons I think it is easiest to keep using frame interval
instead of frame rate.

Actually, that raises a new question: are there codecs that store the frame rate
in the bitstream? I haven't heard of that, so I suspect not, but I'm not certain.

Regards,

	Hans

> 
>>
>> I also chose to make this a codec control, not a generic user control: this
>> value together with the bit rate control(s) determine the compression size,
>> it does not determine the actual time it takes for the encoder to compress
>> the raw frames. Hence it is really not the same thing as the frame interval
> 
> That's a good point.
> 
>> of a video capture device. If we want to use a control for that as well in
>> the future as a replacement for G/S_PARM, then that should be a new control.
>> And we would like need per-pad controls as well in order to implement that.
>> Which is a lot more work.
>>
>> Regards,
>>
>> 	Hans
> 
> 

Re: [PATCHv4 0/2] Document memory-to-memory video codec interfaces

[Nicolas Dufresne]

Le samedi 15 juin 2019 à 10:08 +0200, Hans Verkuil a écrit :
> On 6/14/19 3:09 AM, Nicolas Dufresne wrote:
> > Le jeudi 13 juin 2019 à 08:48 +0200, Hans Verkuil a écrit :
> > > On 6/3/19 1:28 PM, Hans Verkuil wrote:
> > > > Since Tomasz was very busy with other things, I've taken over this
> > > > patch series. This v4 includes his draft changes and additional changes
> > > > from me.
> > > > 
> > > > This series attempts to add the documentation of what was discussed
> > > > during Media Workshops at LinuxCon Europe 2012 in Barcelona and then
> > > > later Embedded Linux Conference Europe 2014 in Düsseldorf and then
> > > > eventually written down by Pawel Osciak and tweaked a bit by Chrome OS
> > > > video team (but mostly in a cosmetic way or making the document more
> > > > precise), during the several years of Chrome OS using the APIs in
> > > > production.
> > > > 
> > > > Note that most, if not all, of the API is already implemented in
> > > > existing mainline drivers, such as s5p-mfc or mtk-vcodec. Intention of
> > > > this series is just to formalize what we already have.
> > > > 
> > > > Thanks everyone for the huge amount of useful comments to previous
> > > > versions of this series. Much of the credits should go to Pawel Osciak
> > > > too, for writing most of the original text of the initial RFC.
> > > > 
> > > > This v4 incorporates all known comments (let me know if I missed
> > > > something!) and should be complete for the decoder.
> > > > 
> > > > For the encoder there are two remaining TODOs for the API:
> > > > 
> > > > 1) Setting the frame rate so bitrate control can make sense, since
> > > >    they need to know this information.
> > > > 
> > > >    Suggested solution: require support for ENUM_FRAMEINTERVALS for the
> > > >    coded pixelformats and S_PARM(OUTPUT). Open question: some drivers
> > > >    (mediatek, hva, coda) require S_PARM(OUTPUT), some (venus) allow both
> > > >    S_PARM(CAPTURE) and S_PARM(OUTPUT). I am inclined to allow both since
> > > >    this is not a CAPTURE vs OUTPUT thing, it is global to both queues.
> > > 
> > > Alternative proposal:
> > > 
> > > 1) Add support for fractions (struct v4l2_fract) as a control type:
> > >    V4L2_CTRL_TYPE_FRACT.
> > > 
> > > 2) Add a new V4L2_CID_MPEG_FRAME_INTERVAL control.
> > 
> > Is the MPEG namespace historical ? That might be confusing for users.
> 
> Yes, it's historical. I have toyed with the idea of renaming all the
> defines to something like V4L2_CID_CODEC_... (keeping the old defines, of
> course), but I'm not sure it is worth it.
> 
> > > Encoders shall support this control.
> > > 
> > > 3) For backwards compatibility reasons encoder drivers still have to
> > > support G/S_PARM, but this can now be implemented by standard helpers
> > > that query this control. Drivers also have to implement ENUM_FRAMEINTERVALS.
> > 
> > That's won't be very friendly for UI generator like qv4l2. Support for
> > v4l2_fract as control should include a way to describe the supported
> > values of that control the usual way I think.
> 
> Such a control will definitely have the usual min/max/step/default control
> values.
> 
> > Also, long term, it would be nice to have two sets of frame rates. The
> > one that the HW can handle "real-time" and the one that can be used for
> > bitrate calculation. So staying away from ENUM_FRAMEINTERVALS for
> > bitrate configuration would be nicer.
> 
> I'm not sure if that's feasible in practice, although the idea is nice.
> The 'real-time' framerate will likely depend to a huge extent on the
> frequency of various internal clocks and the content of the bitstream.
> 
> I suspect it will be very hard if not impossible to report realistic
> ENUM_FRAMEINTERVAL values for codecs.
> 
> > > If the range of intervals is always the same regardless of the frame size,
> > > then a helper can be used that queries the min/max/step of the control, but
> > > if it is dependent on the frame size, then it has to be implemented in the
> > > driver itself.
> > > 
> > > I'm sticking to frame intervals instead of frame rates for the simple reason
> > > that that's what V4L2 has used since the beginning. I think it is too confusing
> > > to change this to a frame rate. This is just my opinion, though.
> > 
> > I suggested frame rate since this is what I saw implemented by HW
> > registers (if you think it's worth it, I can try and make a list).
> > Also, frame-interval steps are not compatible with frame-rate steps
> > (something that was raised through a venus driver bug) last year. Even
> > v4l2-ctl was displaying that in a very confusing way. Something as
> > simple as 1 to 30 fps cannot be exposed through ENU_FRAMEINTERVALS. You
> > are forced to expose the full fractional range of interval, from 1/30
> > to 1/1. For Venus it was not that much of a trouble, since its stores a
> > framerate as Q16..
> 
> Since this is used for bitrate calculations, and not for determining the
> exact framerate, I'm not sure it matters all that much in this particular
> case. Since you still need to implement G/S_PARM in drivers for backwards
> compatibility reasons I think it is easiest to keep using frame interval
> instead of frame rate.
> 
> Actually, that raises a new question: are there codecs that store the frame rate
> in the bitstream? I haven't heard of that, so I suspect not, but I'm not certain.

Yes, H264 and HEVC have the VUI SEI. In HEVC you can also pass this in
VPS. Both are fractions. I'm not certain, but I think you can embed a
timecode, and these also have the fps.

For stateful encoder, it's always nice if the encoder can produce the
SEI/VPS bit. The worst that could happen is an IP that always produce
that information, and userspace that didn't set anything.

For decoders, it's not something I really care about, since I we do
parse this in GStreamer. That being said, I know that the firmware on
the ZynqMP uses the framerate to calculate the number of cores it uses.
So if you don't pass it, it will chose base on the maximum for the
profile/level, which may greatly reduce the number of concurrent
streams you can run.

> 
> Regards,
> 
> 	Hans
> 
> > > I also chose to make this a codec control, not a generic user control: this
> > > value together with the bit rate control(s) determine the compression size,
> > > it does not determine the actual time it takes for the encoder to compress
> > > the raw frames. Hence it is really not the same thing as the frame interval
> > 
> > That's a good point.
> > 
> > > of a video capture device. If we want to use a control for that as well in
> > > the future as a replacement for G/S_PARM, then that should be a new control.
> > > And we would like need per-pad controls as well in order to implement that.
> > > Which is a lot more work.
> > > 
> > > Regards,
> > > 
> > > 	Hans