Late happy new year everyone. It's been a while, but here is the v3 of
the stateful mem2mem codec interfaces documentation. Sorry for taking so
long time to respin. (Again.)
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 for the RFC and
v1. Much of the credits should go to Pawel Osciak too, for writing most
of the original text of the initial RFC.
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 | 1076 +++++++++++++++++
Documentation/media/uapi/v4l/dev-encoder.rst | 586 +++++++++
Documentation/media/uapi/v4l/dev-mem2mem.rst | 6 +
Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 10 +
Documentation/media/uapi/v4l/v4l2.rst | 12 +-
.../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +-
.../media/uapi/v4l/vidioc-encoder-cmd.rst | 38 +-
Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 +
8 files changed, 1752 insertions(+), 30 deletions(-)
create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst
--
2.20.1.321.g9e740568ce-goog

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>
---
Documentation/media/uapi/v4l/dev-decoder.rst | 1076 +++++++++++++++++
Documentation/media/uapi/v4l/dev-mem2mem.rst | 5 +
Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 5 +
Documentation/media/uapi/v4l/v4l2.rst | 10 +-
.../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +-
Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 +
6 files changed, 1135 insertions(+), 15 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..b7db2352ad41
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-decoder.rst
@@ -0,0 +1,1076 @@+.. -*- coding: utf-8; mode: rst -*-
+
+.. _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 encoded
+ bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
+ into ``CAPTURE`` buffers
+
+client
+ application client 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 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 H.264-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
+ 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 H.264 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); 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 H.264 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``
+ required only if cannot be parsed from the stream for the given
+ coded format; optional otherwise - set to zero to ignore
+
+ ``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
+
+ * If width and height are set to non-zero values, the ``CAPTURE`` format
+ will be updated with an appropriate frame buffer resolution instantly.
+ 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. The decoder will derive a new ``CAPTURE`` format from the
+ ``OUTPUT`` format being set, including resolution, colorimetry
+ parameters, etc. If the client needs a specific ``CAPTURE`` format, it
+ must adjust it 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
+ ``V4L2_EVENT_SRC_CH_RESOLUTION`` source change type.
+
+ * 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 sets width and height of the ``OUTPUT`` format to 0,
+ 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 return the ``-EACCES`` error code, until the decoder
+ configures ``CAPTURE`` format according to stream metadata.
+
+ .. 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. Query the minimum number of buffers required for the ``CAPTURE`` queue via
+ :c:func:`VIDIOC_G_CTRL`. This enables the client to request more buffers
+ than the minimum required by hardware/format and achieve better pipelining.
+
+ * **Required fields:**
+
+ ``id``
+ set to ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
+
+ * **Return fields:**
+
+ ``value``
+ minimum number of buffers required to decode the stream parsed in
+ this initialization sequence.
+
+ .. note::
+
+ The minimum number of buffers must be at least the number required to
+ successfully decode the current stream. This may for example be the
+ required DPB size for an H.264 stream given the parsed stream
+ configuration (resolution, level).
+
+ .. warning::
+
+ The value is guaranteed to be meaningful only after the decoder
+ successfully parses the stream metadata. The client must not rely on the
+ query before that happens.
+
+4. **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.
+
+5. **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
+
+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 contents of the source ``OUTPUT`` buffers depend 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 1 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 bufffer 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 opertions 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 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
+ iniitated, 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 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 source change type 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 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 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 the ``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 the ``OUTPUT`` queue, the client must not
+ change the format on the 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..a0e06a88c872 100644
--- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
+++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
@@ -13,6 +13,11 @@
Video Memory-To-Memory Interface
********************************
+.. toctree::
+ :maxdepth: 1
+
+ dev-decoder
+
A V4L2 memory-to-memory device can compress, decompress, transform, or
otherwise convert video data from one format into another format, in memory.
Such memory-to-memory devices set the ``V4L2_CAP_VIDEO_M2M`` or
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..a23ef1b194dc 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,36 @@ 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 stateful mem2mem decoders, 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.
+ No flags or other arguments are accepted in case of mem2mem decoders.
+ 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.
+
+ A stateful mem2mem decoder will proceed with decoding the source
+ buffers pending before the command is issued and then stop producing
+ new frames. It 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 buffer with the
+ ``V4L2_BUF_FLAG_LAST`` flag set was dequeued, the :ref:`VIDIOC_DQBUF
+ <VIDIOC_QBUF>` ioctl will not block anymore, but return an ``EPIPE``
+ error code. No flags or other arguments are accepted in case of mem2mem
+ decoders. See :ref:`decoder` for more details.
* - ``V4L2_DEC_CMD_PAUSE``
- 2
- Pause the decoder. When the decoder has not been started yet, the
diff --git a/Documentation/media/uapi/v4l/vidioc-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst
index e35a9caff652..78980efc0bab 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-fmt.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst
@@ -60,6 +60,13 @@ devices that is either the struct
member. When the requested buffer type is not supported drivers return
an ``EINVAL`` error code.
+A stateful mem2mem decoder will not allow operations on the
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
+buffer type until the corresponding ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` buffer type is configured. If such an
+operation is attempted, drivers return an ``EACCES`` error code. Refer to
+:ref:`decoder` for more details.
+
To change the current format parameters applications initialize the
``type`` field and all fields of the respective ``fmt`` union member.
For details see the documentation of the various devices types in
@@ -157,6 +164,13 @@ 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.
+EACCES
+ The format is not accessible until another buffer type is configured.
+ Relevant for the V4L2_BUF_TYPE_VIDEO_CAPTURE and
+ V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE buffer types of mem2mem decoders, which
+ require the format of V4L2_BUF_TYPE_VIDEO_OUTPUT or
+ V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE buffer type to be configured first.
+
EINVAL
The struct :c:type:`v4l2_format` ``type`` field is
invalid or the requested buffer type not supported.
--
2.20.1.321.g9e740568ce-goog

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>
---
Documentation/media/uapi/v4l/dev-encoder.rst | 586 ++++++++++++++++++
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 | 38 +-
5 files changed, 617 insertions(+), 15 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..fb8b05a132ee
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-encoder.rst
@@ -0,0 +1,586 @@+.. -*- coding: utf-8; mode: rst -*-
+
+.. _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 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.
+
+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_DEC_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(CAPTURE)" ];
+ Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
+
+ Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ];
+ Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
+
+ Stopped -> Encoding [ label = "V4L2_DEC_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 (always zero)
+
+ other fields
+ follow standard semantics
+
+ * **Return fields:**
+
+ ``sizeimage``
+ adjusted size of ``CAPTURE`` buffers
+
+ .. important::
+
+ Changing the ``CAPTURE`` format may change the currently set ``OUTPUT``
+ format. The encoder will derive a new ``OUTPUT`` format from the
+ ``CAPTURE`` format being set, including resolution, colorimetry
+ parameters, etc. If the client needs a specific ``OUTPUT`` format, it
+ must adjust it 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 by encoder to match alignment requirements, as
+ required by the currently selected formats
+
+ other fields
+ follow standard semantics
+
+ * Setting the source resolution will reset the selection rectangles to their
+ default values, based on the new resolution, as described in the step 5
+ below.
+
+4. **Optional.** Set the visible resolution for the stream metadata via
+ :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue.
+
+ * **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.
+
+ ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
+ maximum rectangle within the coded resolution, which the cropped
+ source frame can be composed into; if the hardware does not support
+ composition or scaling, then this is always equal to the rectangle of
+ width and height matching ``V4L2_SEL_TGT_CROP`` and located at (0, 0)
+
+ ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
+ equal to a rectangle of width and height matching
+ ``V4L2_SEL_TGT_CROP`` and located at (0, 0)
+
+ ``V4L2_SEL_TGT_COMPOSE``
+ rectangle within the coded frame, which the cropped source frame
+ is to be composed into; defaults to
+ ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; read-only on hardware without
+ additional compose/scaling capabilities; resulting stream will
+ have this rectangle encoded as the visible rectangle in its
+ metadata
+
+ .. 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,
+
+ * any headers that must be included in a standalone stream must be
+ produced again, e.g. SPS and PPS for H.264.
+
+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 contents of encoded ``CAPTURE`` buffers depend 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 1 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 ``CATPURE`` 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
+ and thus monotonicity of the timestamps cannot be guaranteed.
+
+.. 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.
+
+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 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 decoded 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.
+
+ 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,
+
+* any headers that must be included in a standalone stream must be produced
+ again, e.g. SPS and PPS for H.264.
+
+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, irrespectively of the current ``OUTPUT`` format.
+
+5. While buffers are allocated on the ``CAPTURE`` queue, the client must not
+ change the format on the 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 a0e06a88c872..82630ea89b16 100644
--- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
+++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
@@ -17,6 +17,7 @@ Video Memory-To-Memory Interface
:maxdepth: 1
dev-decoder
+ dev-encoder
A V4L2 memory-to-memory device can compress, decompress, transform, or
otherwise convert video data from one format into another format, in memory.
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..2b59a4e7f5ce 100644
--- a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst
+++ b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst
@@ -57,19 +57,23 @@ currently only used by the STOP command and contains one bit: If the
until the end of the current *Group Of Pictures*, otherwise it will stop
immediately.
-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}|
@@ -114,16 +118,20 @@ introduced in Linux 2.6.21.
- 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.
+
+ A stateful mem2mem encoder will proceed with encoding the source
+ buffers pending before the command is issued and then stop producing
+ new frames. It 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 buffer with the
+ ``V4L2_BUF_FLAG_LAST`` flag set was dequeued, the :ref:`VIDIOC_DQBUF
+ <VIDIOC_QBUF>` ioctl will not block anymore, but return an ``EPIPE``
+ error code. No flags or other arguments are accepted in case of mem2mem
+ encoders. See :ref:`encoder` for more details.
* - ``V4L2_ENC_CMD_PAUSE``
- 2
- Pause the encoder. When the encoder has not been started yet, the
--
2.20.1.321.g9e740568ce-goog

On 01/24/19 11:04, Tomasz Figa wrote:
> Late happy new year everyone. It's been a while, but here is the v3 of
> the stateful mem2mem codec interfaces documentation. Sorry for taking so
> long time to respin. (Again.)
>
> 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 for the RFC and
> v1. Much of the credits should go to Pawel Osciak too, for writing most
> of the original text of the initial RFC.
Thank you very much for this v3.
I've updated the spec with this v3 + Alexandre's v2 incorporated here:
https://hverkuil.home.xs4all.nl/codec-api/uapi/v4l/dev-mem2mem.html
I plan to review this as soon as I can because I really would like to
get this merged for 5.1.
Regards,
Hans
>
> 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 | 1076 +++++++++++++++++
> Documentation/media/uapi/v4l/dev-encoder.rst | 586 +++++++++
> Documentation/media/uapi/v4l/dev-mem2mem.rst | 6 +
> Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 10 +
> Documentation/media/uapi/v4l/v4l2.rst | 12 +-
> .../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +-
> .../media/uapi/v4l/vidioc-encoder-cmd.rst | 38 +-
> Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 +
> 8 files changed, 1752 insertions(+), 30 deletions(-)
> create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> create mode 100644 Documentation/media/uapi/v4l/dev-encoder.rst
>

Hi Tomasz,
Just one typo and a wrong year in a copyright:
On 1/24/19 11:04 AM, Tomasz Figa wrote:
> 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>
> ---
> Documentation/media/uapi/v4l/dev-decoder.rst | 1076 +++++++++++++++++
> Documentation/media/uapi/v4l/dev-mem2mem.rst | 5 +
> Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 5 +
> Documentation/media/uapi/v4l/v4l2.rst | 10 +-
> .../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +-
> Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 +
> 6 files changed, 1135 insertions(+), 15 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..b7db2352ad41
> --- /dev/null
> +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
<snip>
> +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 contents of the source ``OUTPUT`` buffers depend 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 1 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 bufffer 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 opertions on corresponding decoder file handle will return the -EIO
opertions on corresponding decoder -> operations on the corresponding decoder
> +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.
> +
<snip>
> 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
2018 -> 2019
>
> Except when explicitly stated as GPL, programming examples within this
> part can be used and distributed without restrictions.
Just let me know that you are OK with these changes and I can fix up this
patch myself. It looks great and I am ready to merge this patch.
Regards,
Hans

On 1/24/19 11:04 AM, Tomasz Figa wrote:
> 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>
> ---
> Documentation/media/uapi/v4l/dev-decoder.rst | 1076 +++++++++++++++++
> Documentation/media/uapi/v4l/dev-mem2mem.rst | 5 +
> Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 5 +
> Documentation/media/uapi/v4l/v4l2.rst | 10 +-
> .../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +-
> Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 +
> 6 files changed, 1135 insertions(+), 15 deletions(-)
> create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>
<snip>
> +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
> + ``V4L2_EVENT_SRC_CH_RESOLUTION`` source change type.
> +
> + * 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 sets width and height of the ``OUTPUT`` format to 0,
> + 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 return the ``-EACCES`` error code, until the decoder
> + configures ``CAPTURE`` format according to stream metadata.
I think this should also include the G/S_SELECTION ioctls, right?
Regards,
Hans

On 1/31/19 11:45 AM, Hans Verkuil wrote:
> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>> 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>
>> ---
>> Documentation/media/uapi/v4l/dev-decoder.rst | 1076 +++++++++++++++++
>> Documentation/media/uapi/v4l/dev-mem2mem.rst | 5 +
>> Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 5 +
>> Documentation/media/uapi/v4l/v4l2.rst | 10 +-
>> .../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +-
>> Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 +
>> 6 files changed, 1135 insertions(+), 15 deletions(-)
>> create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>>
>
> <snip>
>
>> +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
>> + ``V4L2_EVENT_SRC_CH_RESOLUTION`` source change type.
>> +
>> + * 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 sets width and height of the ``OUTPUT`` format to 0,
>> + 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 return the ``-EACCES`` error code, until the decoder
>> + configures ``CAPTURE`` format according to stream metadata.
>
> I think this should also include the G/S_SELECTION ioctls, right?
I've started work on adding compliance tests for codecs to v4l2-compliance and
I quickly discovered that this 'EACCES' error code is not nice at all.
The problem is that it is really inconsistent with V4L2 behavior: the basic
rule is that there always is a format defined, i.e. G_FMT will always return
a format.
Suddenly returning an error is actually quite painful to handle because it is
a weird exception just for the capture queue of a stateful decoder if no
output resolution is known.
Just writing that sentence is painful.
Why not just return some default driver defined format? It will automatically
be updated once the decoder parsed the bitstream and knows the new resolution.
It really is just the same behavior as with a resolution change.
It is also perfectly fine to request buffers for the capture queue for that
default format. It's pointless, but not a bug.
Unless I am missing something I strongly recommend changing this behavior.
Regards,
Hans

On 1/31/19 1:30 PM, Hans Verkuil wrote:
> On 1/31/19 11:45 AM, Hans Verkuil wrote:
>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>>> 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>
>>> ---
>>> Documentation/media/uapi/v4l/dev-decoder.rst | 1076 +++++++++++++++++
>>> Documentation/media/uapi/v4l/dev-mem2mem.rst | 5 +
>>> Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 5 +
>>> Documentation/media/uapi/v4l/v4l2.rst | 10 +-
>>> .../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +-
>>> Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 +
>>> 6 files changed, 1135 insertions(+), 15 deletions(-)
>>> create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>>>
>>
>> <snip>
>>
>>> +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
>>> + ``V4L2_EVENT_SRC_CH_RESOLUTION`` source change type.
>>> +
>>> + * 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 sets width and height of the ``OUTPUT`` format to 0,
>>> + 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 return the ``-EACCES`` error code, until the decoder
>>> + configures ``CAPTURE`` format according to stream metadata.
>>
>> I think this should also include the G/S_SELECTION ioctls, right?
>
> I've started work on adding compliance tests for codecs to v4l2-compliance and
> I quickly discovered that this 'EACCES' error code is not nice at all.
>
> The problem is that it is really inconsistent with V4L2 behavior: the basic
> rule is that there always is a format defined, i.e. G_FMT will always return
> a format.
>
> Suddenly returning an error is actually quite painful to handle because it is
> a weird exception just for the capture queue of a stateful decoder if no
> output resolution is known.
>
> Just writing that sentence is painful.
Note that adding EACCES support in vicodec was just as painful as adding
v4l2-compliance support for it. So it is also easier to handle this in
the driver if you can just set up a default format.
Regards,
Hans
>
> Why not just return some default driver defined format? It will automatically
> be updated once the decoder parsed the bitstream and knows the new resolution.
>
> It really is just the same behavior as with a resolution change.
>
> It is also perfectly fine to request buffers for the capture queue for that
> default format. It's pointless, but not a bug.
>
> Unless I am missing something I strongly recommend changing this behavior.
>
> Regards,
>
> Hans
>

On 1/31/19 1:44 PM, Philipp Zabel wrote:
> On Thu, 2019-01-31 at 13:30 +0100, Hans Verkuil wrote:
>> On 1/31/19 11:45 AM, Hans Verkuil wrote:
>>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>>>> 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>
>>>> ---
>>>> Documentation/media/uapi/v4l/dev-decoder.rst | 1076 +++++++++++++++++
>>>> Documentation/media/uapi/v4l/dev-mem2mem.rst | 5 +
>>>> Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 5 +
>>>> Documentation/media/uapi/v4l/v4l2.rst | 10 +-
>>>> .../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +-
>>>> Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 +
>>>> 6 files changed, 1135 insertions(+), 15 deletions(-)
>>>> create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
>>>>
>>>
>>> <snip>
>>>
>>>> +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
>>>> + ``V4L2_EVENT_SRC_CH_RESOLUTION`` source change type.
>>>> +
>>>> + * 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 sets width and height of the ``OUTPUT`` format to 0,
>>>> + 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 return the ``-EACCES`` error code, until the decoder
>>>> + configures ``CAPTURE`` format according to stream metadata.
>>>
>>> I think this should also include the G/S_SELECTION ioctls, right?
>>
>> I've started work on adding compliance tests for codecs to v4l2-compliance and
>> I quickly discovered that this 'EACCES' error code is not nice at all.
>>
>> The problem is that it is really inconsistent with V4L2 behavior: the basic
>> rule is that there always is a format defined, i.e. G_FMT will always return
>> a format.
>>
>> Suddenly returning an error is actually quite painful to handle because it is
>> a weird exception just for the capture queue of a stateful decoder if no
>> output resolution is known.
>>
>> Just writing that sentence is painful.
>>
>> Why not just return some default driver defined format? It will automatically
>> be updated once the decoder parsed the bitstream and knows the new resolution.
>>
>> It really is just the same behavior as with a resolution change.
>>
>> It is also perfectly fine to request buffers for the capture queue for that
>> default format. It's pointless, but not a bug.
>>
>> Unless I am missing something I strongly recommend changing this behavior.
>
> I just wrote the same in my reply to Nicolas, the CODA driver currently
> sets the capture queue width/height to the output queue's crop rectangle
> (rounded to macroblock size) without ever having seen the SPS.
And thinking about the initial 0x0 width/height for the output queue:
that too is an exception, although less of a problem than the EACCES behavior.
It should be fine for an application to set width/height to 0 when calling
S_FMT for the output queue of the decoder, but I would also prefer that it is
just replaced by the driver with some default resolution. It really doesn't
matter in practice, since you will wait for the SOURCE_CHANGE event regardless.
Only then do you start to configure the CAPTURE queue.
Using 0x0 and EACCES looks good on paper, but in the code it is a hassle and
I'm not convinced there is any benefit.
I like generic APIs and no where else do we ever return a 0 value for width
or height, except in this corner case. It's just awkward.
Regards,
Hans

On Thu, Jan 31, 2019 at 10:19 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>
> On 1/31/19 1:44 PM, Philipp Zabel wrote:
> > On Thu, 2019-01-31 at 13:30 +0100, Hans Verkuil wrote:
> >> On 1/31/19 11:45 AM, Hans Verkuil wrote:
> >>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
> >>>> 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>
> >>>> ---
> >>>> Documentation/media/uapi/v4l/dev-decoder.rst | 1076 +++++++++++++++++
> >>>> Documentation/media/uapi/v4l/dev-mem2mem.rst | 5 +
> >>>> Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 5 +
> >>>> Documentation/media/uapi/v4l/v4l2.rst | 10 +-
> >>>> .../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +-
> >>>> Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 +
> >>>> 6 files changed, 1135 insertions(+), 15 deletions(-)
> >>>> create mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst
> >>>>
> >>>
> >>> <snip>
> >>>
> >>>> +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
> >>>> + ``V4L2_EVENT_SRC_CH_RESOLUTION`` source change type.
> >>>> +
> >>>> + * 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 sets width and height of the ``OUTPUT`` format to 0,
> >>>> + 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 return the ``-EACCES`` error code, until the decoder
> >>>> + configures ``CAPTURE`` format according to stream metadata.
> >>>
> >>> I think this should also include the G/S_SELECTION ioctls, right?
> >>
> >> I've started work on adding compliance tests for codecs to v4l2-compliance and
> >> I quickly discovered that this 'EACCES' error code is not nice at all.
> >>
> >> The problem is that it is really inconsistent with V4L2 behavior: the basic
> >> rule is that there always is a format defined, i.e. G_FMT will always return
> >> a format.
> >>
> >> Suddenly returning an error is actually quite painful to handle because it is
> >> a weird exception just for the capture queue of a stateful decoder if no
> >> output resolution is known.
> >>
> >> Just writing that sentence is painful.
> >>
> >> Why not just return some default driver defined format? It will automatically
> >> be updated once the decoder parsed the bitstream and knows the new resolution.
> >>
> >> It really is just the same behavior as with a resolution change.
> >>
> >> It is also perfectly fine to request buffers for the capture queue for that
> >> default format. It's pointless, but not a bug.
> >>
> >> Unless I am missing something I strongly recommend changing this behavior.
> >
> > I just wrote the same in my reply to Nicolas, the CODA driver currently
> > sets the capture queue width/height to the output queue's crop rectangle
> > (rounded to macroblock size) without ever having seen the SPS.
>
> And thinking about the initial 0x0 width/height for the output queue:
>
> that too is an exception, although less of a problem than the EACCES behavior.
>
> It should be fine for an application to set width/height to 0 when calling
> S_FMT for the output queue of the decoder, but I would also prefer that it is
> just replaced by the driver with some default resolution. It really doesn't
> matter in practice, since you will wait for the SOURCE_CHANGE event regardless.
>
> Only then do you start to configure the CAPTURE queue.
>
> Using 0x0 and EACCES looks good on paper, but in the code it is a hassle and
> I'm not convinced there is any benefit.
>
> I like generic APIs and no where else do we ever return a 0 value for width
> or height, except in this corner case. It's just awkward.
Agreed, although with some caveats I mentioned in my reply to the venus patch.
Best regards,
Tomasz

Hi Tomasz,
Some more comments...
On 1/29/19 2:52 PM, Hans Verkuil wrote:
> Hi Tomasz,
>
> Some comments below. Nothing major, so I think a v4 should be ready to be
> merged.
>
> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>> 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>
>> ---
>> Documentation/media/uapi/v4l/dev-encoder.rst | 586 ++++++++++++++++++
>> 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 | 38 +-
>> 5 files changed, 617 insertions(+), 15 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..fb8b05a132ee
>> --- /dev/null
>> +++ b/Documentation/media/uapi/v4l/dev-encoder.rst
>> @@ -0,0 +1,586 @@
>> +.. -*- coding: utf-8; mode: rst -*-
>> +
>> +.. _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 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.
>> +
>> +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_DEC_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(CAPTURE)" ];
>> + Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
>> +
>> + Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ];
>> + Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
>> +
>> + Stopped -> Encoding [ label = "V4L2_DEC_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 (always zero)
>> +
>> + other fields
>> + follow standard semantics
>> +
>> + * **Return fields:**
>> +
>> + ``sizeimage``
>> + adjusted size of ``CAPTURE`` buffers
>> +
>> + .. important::
>> +
>> + Changing the ``CAPTURE`` format may change the currently set ``OUTPUT``
>> + format. The encoder will derive a new ``OUTPUT`` format from the
>> + ``CAPTURE`` format being set, including resolution, colorimetry
>> + parameters, etc. If the client needs a specific ``OUTPUT`` format, it
>> + must adjust it afterwards.
>
> Hmm, "including resolution": if width and height are set to 0, what should the
> OUTPUT resolution be? Up to the driver? I think this should be clarified since
> at a first reading of this paragraph it appears to be contradictory.
I think the driver should just return the width and height of the OUTPUT
format. So the width and height that userspace specifies is just ignored
and replaced by the width and height of the OUTPUT format. After all, that's
what the bitstream will encode. Returning 0 for width and height would make
this a strange exception in V4L2 and I want to avoid that.
>
>> +
>> +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 by encoder to match alignment requirements, as
>> + required by the currently selected formats
>
> What if the width x height is larger than the maximum supported by the
> selected coded format? This should probably mention that in that case the
> width x height is reduced to the largest allowed value. Also mention that
> this maximum is reported by VIDIOC_ENUM_FRAMESIZES.
>
>> +
>> + other fields
>> + follow standard semantics
>> +
>> + * Setting the source resolution will reset the selection rectangles to their
>> + default values, based on the new resolution, as described in the step 5
>
> 5 -> 4
>
> Or just say: "as described in the next step."
>
>> + below.
It should also be made explicit that:
1) the crop rectangle will be set to the given width and height *before*
it is being adjusted by S_FMT.
Open question: should we support a compose rectangle for the CAPTURE that
is the same as the OUTPUT crop rectangle? I.e. the CAPTURE format contains
the adjusted width and height and the compose rectangle (read-only) contains
the visible width and height. It's not strictly necessary, but it is
symmetrical.
2) the CAPTURE format will be updated as well with the new OUTPUT width and
height. The CAPTURE sizeimage might change as well.
>> +
>> +4. **Optional.** Set the visible resolution for the stream metadata via
>> + :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue.
I think you should mention that this is only necessary if the crop rectangle
that is set when you set the format isn't what you want.
>> +
>> + * **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.
This last sentence contradicts the proposed behavior of S_FMT(OUTPUT).
>> +
>> + ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
>> + maximum rectangle within the coded resolution, which the cropped
>> + source frame can be composed into; if the hardware does not support
>> + composition or scaling, then this is always equal to the rectangle of
>> + width and height matching ``V4L2_SEL_TGT_CROP`` and located at (0, 0)
>> +
>> + ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
>> + equal to a rectangle of width and height matching
>> + ``V4L2_SEL_TGT_CROP`` and located at (0, 0)
>> +
>> + ``V4L2_SEL_TGT_COMPOSE``
>> + rectangle within the coded frame, which the cropped source frame
>> + is to be composed into; defaults to
>> + ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; read-only on hardware without
>> + additional compose/scaling capabilities; resulting stream will
>> + have this rectangle encoded as the visible rectangle in its
>> + metadata
I think the compose targets for OUTPUT are only needed if the hardware can
actually do scaling and/or composition. Otherwise they can (must?) be
dropped.
>> +
>> + .. 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,
>> +
>> + * any headers that must be included in a standalone stream must be
>> + produced again, e.g. SPS and PPS for H.264.
>> +
>> +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 contents of encoded ``CAPTURE`` buffers depend 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 1 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 ``CATPURE`` 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
>> + and thus monotonicity of the timestamps cannot be guaranteed.
>
> Drop "and thus monotonicity of the timestamps cannot be guaranteed": this was never
> guaranteed since timestamps are just copied from OUTPUT to CAPTURE.
>
> This phrase doesn't occur in the decoder spec, so it should be removed here as well.
>
>> +
>> +.. 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.
>> +
>> +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 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 decoded 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.
>> +
>> + 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,
>> +
>> +* any headers that must be included in a standalone stream must be produced
>> + again, e.g. SPS and PPS for H.264.
>> +
>> +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, irrespectively of the current ``OUTPUT`` format.
>
> irrespectively -> irrespective
>
>> +
>> +5. While buffers are allocated on the ``CAPTURE`` queue, the client must not
>> + change the format on the queue. Drivers will return the -EBUSY error code
Change the format on which queue? CAPTURE or OUTPUT?
I think this should be more precise: changing the CAPTURE format will always
fail if CAPTURE buffers are already allocated, or if the OUTPUT is streaming,
or if changing the CAPTURE format will change the OUTPUT format and OUTPUT
buffers are already allocated.
Changing the OUTPUT format will always fail if OUTPUT buffers are already allocated,
or if changing the OUTPUT format would change the CAPTURE format (sizeimage in
particular) and CAPTURE buffers were already allocated and are too small.
Regards,
Hans
>> + 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 a0e06a88c872..82630ea89b16 100644
>> --- a/Documentation/media/uapi/v4l/dev-mem2mem.rst
>> +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
>> @@ -17,6 +17,7 @@ Video Memory-To-Memory Interface
>> :maxdepth: 1
>>
>> dev-decoder
>> + dev-encoder
>>
>> A V4L2 memory-to-memory device can compress, decompress, transform, or
>> otherwise convert video data from one format into another format, in memory.
>> 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..2b59a4e7f5ce 100644
>> --- a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst
>> +++ b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst
>> @@ -57,19 +57,23 @@ currently only used by the STOP command and contains one bit: If the
>> until the end of the current *Group Of Pictures*, otherwise it will stop
>> immediately.
>>
>> -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}|
>> @@ -114,16 +118,20 @@ introduced in Linux 2.6.21.
>> - 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.
>> +
>> + A stateful mem2mem encoder will proceed with encoding the source
>> + buffers pending before the command is issued and then stop producing
>> + new frames. It 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 buffer with the
>> + ``V4L2_BUF_FLAG_LAST`` flag set was dequeued, the :ref:`VIDIOC_DQBUF
>> + <VIDIOC_QBUF>` ioctl will not block anymore, but return an ``EPIPE``
>> + error code. No flags or other arguments are accepted in case of mem2mem
>> + encoders. See :ref:`encoder` for more details.
>> * - ``V4L2_ENC_CMD_PAUSE``
>> - 2
>> - Pause the encoder. When the encoder has not been started yet, the
>>
>
> Regards,
>
> Hans
>

Another comment found while creating compliance tests:
On 1/24/19 11:04 AM, Tomasz Figa wrote:
> +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 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 decoded 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,
I assume that calling CMD_START when *not* draining will succeed but does nothing.
In other words: while draining is in progress START will return EBUSY. When draining
was finished, then START will resume the encoder. In all other cases it just returns
0 since the encoder is really already started.
> +
> + * 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.
I assume calling STOP again once the drain sequence completed just returns 0 and
doesn't do anything else (since we're already stopped).
> +
> + Although mandatory, the availability of encoder commands may be queried
> + using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
Some corner cases:
1) No buffers are queued on either vb2_queue, but STREAMON is called for both queues.
Now ENC_CMD_STOP is issued. What should happen?
Proposal: the next time the applications queues a CAPTURE buffer it is returned
at once as an empty buffer with FLAG_LAST set.
2) Both queues are streaming and buffers have been encoded, but currently no buffers
are queued on either vb2_queue. Now ENC_CMD_STOP is issued. What should happen?
Proposal: the next time the applications queues a CAPTURE buffer it is returned
at once as an empty buffer with FLAG_LAST set. This is consistent with the
previous corner case.
3) The CAPTURE queue contains buffers, the OUTPUT queue does not. Now ENC_CMD_STOP
is issued. What should happen?
Proposal: the oldest CAPTURE buffer in the ready queue is returned as an empty
buffer with FLAG_LAST set.
4) Both queues have queued buffers. ENC_CMD_STOP is issued to start the drain process.
Before the drain process completes STREAMOFF is called for either CAPTURE or
OUTPUT queue. What should happen?
Proposal for STREAMOFF(CAPTURE): aborts the drain process and all CAPTURE buffers are
returned to userspace. If encoding is restarted, then any remaining OUTPUT buffers
will be used as input to the encoder.
Proposal for STREAMOFF(OUTPUT): the next capture buffer will be empty and have
FLAG_LAST set.
Some of this might have to be documented, but these corner cases should certainly be
tested by v4l2-compliance. Before I write those tests I'd like to know if you agree
with this.
Regards,
Hans

On 3/25/19 2:12 PM, Hans Verkuil wrote:
> Another comment found while creating compliance tests:
>
> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>> +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 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 decoded 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,
>
> I assume that calling CMD_START when *not* draining will succeed but does nothing.
>
> In other words: while draining is in progress START will return EBUSY. When draining
> was finished, then START will resume the encoder. In all other cases it just returns
> 0 since the encoder is really already started.
>
>> +
>> + * 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.
>
> I assume calling STOP again once the drain sequence completed just returns 0 and
> doesn't do anything else (since we're already stopped).
>
>> +
>> + Although mandatory, the availability of encoder commands may be queried
>> + using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
>
> Some corner cases:
>
> 1) No buffers are queued on either vb2_queue, but STREAMON is called for both queues.
> Now ENC_CMD_STOP is issued. What should happen?
>
> Proposal: the next time the applications queues a CAPTURE buffer it is returned
> at once as an empty buffer with FLAG_LAST set.
>
> 2) Both queues are streaming and buffers have been encoded, but currently no buffers
> are queued on either vb2_queue. Now ENC_CMD_STOP is issued. What should happen?
>
> Proposal: the next time the applications queues a CAPTURE buffer it is returned
> at once as an empty buffer with FLAG_LAST set. This is consistent with the
> previous corner case.
>
> 3) The CAPTURE queue contains buffers, the OUTPUT queue does not. Now ENC_CMD_STOP
> is issued. What should happen?
>
> Proposal: the oldest CAPTURE buffer in the ready queue is returned as an empty
> buffer with FLAG_LAST set.
>
> 4) Both queues have queued buffers. ENC_CMD_STOP is issued to start the drain process.
> Before the drain process completes STREAMOFF is called for either CAPTURE or
> OUTPUT queue. What should happen?
>
> Proposal for STREAMOFF(CAPTURE): aborts the drain process and all CAPTURE buffers are
> returned to userspace. If encoding is restarted, then any remaining OUTPUT buffers
> will be used as input to the encoder.
>
> Proposal for STREAMOFF(OUTPUT): the next capture buffer will be empty and have
> FLAG_LAST set.
Note: I'm not quite sure about that last one yet. It's a bit tricky to implement.
I think some of these rules might have to be implemented in v4l2-mem2mem.c to
simplify drivers.
Regards,
Hans
>
> Some of this might have to be documented, but these corner cases should certainly be
> tested by v4l2-compliance. Before I write those tests I'd like to know if you agree
> with this.
>
> Regards,
>
> Hans
>

On 4/5/19 10:12 AM, Tomasz Figa wrote:
> On Thu, Mar 14, 2019 at 10:57 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>
>> Hi Tomasz,
>>
>> Some more comments...
>>
>> On 1/29/19 2:52 PM, Hans Verkuil wrote:
>>> Hi Tomasz,
>>>
>>> Some comments below. Nothing major, so I think a v4 should be ready to be
>>> merged.
>>>
>>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>>>> 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>
>>>> ---
>>>> Documentation/media/uapi/v4l/dev-encoder.rst | 586 ++++++++++++++++++
>>>> 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 | 38 +-
>>>> 5 files changed, 617 insertions(+), 15 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..fb8b05a132ee
>>>> --- /dev/null
>>>> +++ b/Documentation/media/uapi/v4l/dev-encoder.rst
>>>> @@ -0,0 +1,586 @@
>>>> +.. -*- coding: utf-8; mode: rst -*-
>>>> +
>>>> +.. _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 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.
>>>> +
>>>> +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_DEC_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(CAPTURE)" ];
>>>> + Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
>>>> +
>>>> + Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ];
>>>> + Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
>>>> +
>>>> + Stopped -> Encoding [ label = "V4L2_DEC_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 (always zero)
>>>> +
>>>> + other fields
>>>> + follow standard semantics
>>>> +
>>>> + * **Return fields:**
>>>> +
>>>> + ``sizeimage``
>>>> + adjusted size of ``CAPTURE`` buffers
>>>> +
>>>> + .. important::
>>>> +
>>>> + Changing the ``CAPTURE`` format may change the currently set ``OUTPUT``
>>>> + format. The encoder will derive a new ``OUTPUT`` format from the
>>>> + ``CAPTURE`` format being set, including resolution, colorimetry
>>>> + parameters, etc. If the client needs a specific ``OUTPUT`` format, it
>>>> + must adjust it afterwards.
>>>
>>> Hmm, "including resolution": if width and height are set to 0, what should the
>>> OUTPUT resolution be? Up to the driver? I think this should be clarified since
>>> at a first reading of this paragraph it appears to be contradictory.
>>
>> I think the driver should just return the width and height of the OUTPUT
>> format. So the width and height that userspace specifies is just ignored
>> and replaced by the width and height of the OUTPUT format. After all, that's
>> what the bitstream will encode. Returning 0 for width and height would make
>> this a strange exception in V4L2 and I want to avoid that.
>>
>
> Hmm, however, the width and height of the OUTPUT format is not what's
> actually encoded in the bitstream. The right selection rectangle
> determines that.
>
> In one of the previous versions I though we could put the codec
> resolution as the width and height of the CAPTURE format, which would
> be the resolution of the encoded image rounded up to full macroblocks
> +/- some encoder-specific constraints. AFAIR there was some concern
> about OUTPUT format changes triggering CAPTURE format changes, but to
> be honest, I'm not sure if that's really a problem. I just decided to
> drop that for the simplicity.
I'm not sure what your point is.
The OUTPUT format has the coded resolution, so when you set the
CAPTURE format it can just copy the OUTPUT coded resolution unless the
chosen CAPTURE pixelformat can't handle that in which case both the
OUTPUT and CAPTURE coded resolutions are clamped to whatever is the maximum
or minimum the codec is capable of.
That said, I am fine with just leaving it up to the driver as suggested
before. Just as long as both the CAPTURE and OUTPUT formats remain valid
(i.e. width and height may never be out of range).
>
>>>
>>>> +
>>>> +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 by encoder to match alignment requirements, as
>>>> + required by the currently selected formats
>>>
>>> What if the width x height is larger than the maximum supported by the
>>> selected coded format? This should probably mention that in that case the
>>> width x height is reduced to the largest allowed value. Also mention that
>>> this maximum is reported by VIDIOC_ENUM_FRAMESIZES.
>>>
>>>> +
>>>> + other fields
>>>> + follow standard semantics
>>>> +
>>>> + * Setting the source resolution will reset the selection rectangles to their
>>>> + default values, based on the new resolution, as described in the step 5
>>>
>>> 5 -> 4
>>>
>>> Or just say: "as described in the next step."
>>>
>>>> + below.
>>
>> It should also be made explicit that:
>>
>> 1) the crop rectangle will be set to the given width and height *before*
>> it is being adjusted by S_FMT.
>>
>
> I don't think that's what we want here.
>
> Defining the default rectangle to be exactly the same as the OUTPUT
> resolution (after the adjustment) makes the semantics consistent - not
> setting the crop rectangle gives you exactly the behavior as if there
> was no cropping involved (or supported by the encoder).
I think you are right. This seems to be what the coda driver does as well.
It is convenient to be able to just set a 1920x1080 format and have that
resolution be stored as the crop rectangle, since it avoids having to call
s_selection afterwards, but it is not really consistent with the way V4L2
works.
>
>> Open question: should we support a compose rectangle for the CAPTURE that
>> is the same as the OUTPUT crop rectangle? I.e. the CAPTURE format contains
>> the adjusted width and height and the compose rectangle (read-only) contains
>> the visible width and height. It's not strictly necessary, but it is
>> symmetrical.
>
> Wouldn't it rather be the CAPTURE crop rectangle that would be of the
> same resolution of the OUTPUT compose rectangle? Then you could
> actually have the CAPTURE compose rectangle for putting that into the
> desired rectangle of the encoded stream, if the encoder supports that.
> (I don't know any that does, so probably out of concern for now.)
Yes, you are right.
But should we support this?
I actually think not for this initial version. It can be added later, I guess.
>
>>
>> 2) the CAPTURE format will be updated as well with the new OUTPUT width and
>> height. The CAPTURE sizeimage might change as well.
>>
>>>> +
>>>> +4. **Optional.** Set the visible resolution for the stream metadata via
>>>> + :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue.
>>
>> I think you should mention that this is only necessary if the crop rectangle
>> that is set when you set the format isn't what you want.
>>
>
> Ack.
>
>>>> +
>>>> + * **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.
>>
>> This last sentence contradicts the proposed behavior of S_FMT(OUTPUT).
>>
>
> Sorry, which part exactly and what part of the proposal exactly? :)
> (My comment above might be related, though.)
Ignore my comment. We go back to explicitly requiring userspace to set the OUTPUT
crop selection target, so this note remains valid.
>
>>>> +
>>>> + ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
>>>> + maximum rectangle within the coded resolution, which the cropped
>>>> + source frame can be composed into; if the hardware does not support
>>>> + composition or scaling, then this is always equal to the rectangle of
>>>> + width and height matching ``V4L2_SEL_TGT_CROP`` and located at (0, 0)
>>>> +
>>>> + ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
>>>> + equal to a rectangle of width and height matching
>>>> + ``V4L2_SEL_TGT_CROP`` and located at (0, 0)
>>>> +
>>>> + ``V4L2_SEL_TGT_COMPOSE``
>>>> + rectangle within the coded frame, which the cropped source frame
>>>> + is to be composed into; defaults to
>>>> + ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; read-only on hardware without
>>>> + additional compose/scaling capabilities; resulting stream will
>>>> + have this rectangle encoded as the visible rectangle in its
>>>> + metadata
>>
>> I think the compose targets for OUTPUT are only needed if the hardware can
>> actually do scaling and/or composition. Otherwise they can (must?) be
>> dropped.
>>
>
> Note that V4L2_SEL_TGT_COMPOSE is defined to be the way for the
> userspace to learn the target visible rectangle that's going to be
> encoded in the stream metadata. If we omit it, we wouldn't have a way
> that would be consistent between encoders that can do
> scaling/composition and those that can't.
I'm not convinced about this. The standard API behavior is not to expose
functionality that the hardware can't do. So if scaling isn't possible on
the OUTPUT side, then it shouldn't expose OUTPUT compose rectangles.
I also believe it very unlikely that we'll see encoders capable of scaling
as it doesn't make much sense. I would prefer to drop this to simplify the
spec, and when we get encoders that can scale, then we can add support for
compose rectangles (and I'm sure we'll need to think about how that
influences the CAPTURE side as well).
For encoders without scaling it is the OUTPUT crop rectangle that defines
the visible rectangle.
>
> However, with your proposal of actually having selection rectangles
> for the CAPTURE queue, it could be solved indeed. The OUTPUT queue
> would expose a varying set of rectangles, depending on the hardware
> capability, while the CAPTURE queue would always expose its rectangle
> with that information.
I think we should keep it simple and only define selection rectangles
when really needed.
So encoders support CROP on the OUTPUT, and decoders support CAPTURE
COMPOSE (may be read-only). Nothing else.
Once support for scaling is needed (either on the encoder or decoder
side), then the spec should be enhanced. But I prefer to postpone that
until we actually have hardware that needs this.
>
>>>> +
>>>> + .. 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,
>>>> +
>>>> + * any headers that must be included in a standalone stream must be
>>>> + produced again, e.g. SPS and PPS for H.264.
>>>> +
>>>> +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 contents of encoded ``CAPTURE`` buffers depend 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 1 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 ``CATPURE`` 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
>>>> + and thus monotonicity of the timestamps cannot be guaranteed.
>>>
>>> Drop "and thus monotonicity of the timestamps cannot be guaranteed": this was never
>>> guaranteed since timestamps are just copied from OUTPUT to CAPTURE.
>>>
>>> This phrase doesn't occur in the decoder spec, so it should be removed here as well.
>>>
>>>> +
>>>> +.. 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.
>>>> +
>>>> +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 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 decoded 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.
>>>> +
>>>> + 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,
>>>> +
>>>> +* any headers that must be included in a standalone stream must be produced
>>>> + again, e.g. SPS and PPS for H.264.
>>>> +
>>>> +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, irrespectively of the current ``OUTPUT`` format.
>>>
>>> irrespectively -> irrespective
>>>
>>>> +
>>>> +5. While buffers are allocated on the ``CAPTURE`` queue, the client must not
>>>> + change the format on the queue. Drivers will return the -EBUSY error code
>>
>> Change the format on which queue? CAPTURE or OUTPUT?
>
> CAPTURE was intended here. One should be able to change the format on
> OUTPUT freely.
Ack.
>
>>
>> I think this should be more precise: changing the CAPTURE format will always
>> fail if CAPTURE buffers are already allocated, or if the OUTPUT is streaming,
>> or if changing the CAPTURE format will change the OUTPUT format and OUTPUT
>> buffers are already allocated.
>
> Indeed. I believe we can generalize this to:
>
> 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.
Sounds good.
>
>>
>> Changing the OUTPUT format will always fail if OUTPUT buffers are already allocated,
>> or if changing the OUTPUT format would change the CAPTURE format (sizeimage in
>> particular) and CAPTURE buffers were already allocated and are too small.
>
> The OUTPUT format must not change the CAPTURE format by definition.
> Otherwise we end up in a situation where we can't commit, because both
> queue formats can affect each other. Any change to the OUTPUT format
> that wouldn't work with the current CAPTURE format should be adjusted
> by the driver to match the current CAPTURE format.
But the CAPTURE format *does* depend on the OUTPUT format: if the output
resolution changes, then so does the CAPTURE resolution and esp. the
sizeimage value, since that is typically resolution dependent.
The coda driver does this as well: changing the output resolution
will update the capture resolution and sizeimage. The vicodec driver does the
same.
Setting the CAPTURE format basically just selects the codec to use, after
that you can set the OUTPUT format and read the updated CAPTURE format to
get the new sizeimage value. In fact, setting the CAPTURE format shouldn't
change the OUTPUT format, unless the OUTPUT format is incompatible with the
newly selected codec.
Regards,
Hans

On 4/5/19 12:59 PM, Philipp Zabel wrote:
> On Thu, 2019-01-24 at 19:04 +0900, Tomasz Figa wrote:
>> 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>
>> ---
>> Documentation/media/uapi/v4l/dev-decoder.rst | 1076 +++++++++++++++++
>> Documentation/media/uapi/v4l/dev-mem2mem.rst | 5 +
>> Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 5 +
>> Documentation/media/uapi/v4l/v4l2.rst | 10 +-
>> .../media/uapi/v4l/vidioc-decoder-cmd.rst | 40 +-
>> Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 14 +
>> 6 files changed, 1135 insertions(+), 15 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..b7db2352ad41
>> --- /dev/null
>> +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
>> @@ -0,0 +1,1076 @@
>> +.. -*- coding: utf-8; mode: rst -*-
>> +
>> +.. _decoder:
>> +
>> +*************************************************
>> +Memory-to-memory Stateful Video Decoder Interface
>> +*************************************************
>> +
> [...]
>> +
>> +Drain
>> +=====
>> +
> [...]
>> +
>> +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:
>> +
> [...]
>> +
>> +.. 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.
>
> Should the V4L2_DEC_CMD_STOP documentation in
> Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst:
>
> * - ``V4L2_DEC_CMD_STOP``
> - 1
> - Stop the decoder. When the decoder is already stopped, this
> command does nothing.
>
> be updated to mention that for mem2mem decoders this not only does
> nothing, but returns an -EBUSY error return value?
Yes. Basically in this case the STOP is still in progress, so returning
EBUSY makes sense and should be documented.
>
> Also, if V4L2_DEC_CMD_STOP_IMMEDIATELY is set, should the decoder drop
> all pending buffers and signal EOS immediately? Should this be mentioned
> here?
Hmm, the decoder spec says that flags should be set to 0, and current codec
drivers explicitly disallow a non-0 flags value.
I'm not sure if there is a practical use-case for V4L2_DEC_CMD_STOP_IMMEDIATELY
in the context of a decoder. If you want to stop immediately, then just call
streamoff on the OUTPUT queue.
>
>> + Although mandatory, the availability of decoder commands may be queried
>> + using :c:func:`VIDIOC_TRY_DECODER_CMD`.
>
> Do the TRY_DECODER_CMD also return -EBUSY during the draining phase?
No.
Regards,
Hans
>
> regards
> Philipp
>

On Mon, Mar 25, 2019 at 10:12 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>
> Another comment found while creating compliance tests:
>
> On 1/24/19 11:04 AM, Tomasz Figa wrote:
> > +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 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 decoded 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,
>
> I assume that calling CMD_START when *not* draining will succeed but does nothing.
>
> In other words: while draining is in progress START will return EBUSY. When draining
> was finished, then START will resume the encoder. In all other cases it just returns
> 0 since the encoder is really already started.
>
Yes, that was the intention and seems to be the closest to the
behavior described in the existing documentation.
> > +
> > + * 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.
>
> I assume calling STOP again once the drain sequence completed just returns 0 and
> doesn't do anything else (since we're already stopped).
>
Right.
> > +
> > + Although mandatory, the availability of encoder commands may be queried
> > + using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
>
> Some corner cases:
>
> 1) No buffers are queued on either vb2_queue, but STREAMON is called for both queues.
> Now ENC_CMD_STOP is issued. What should happen?
>
> Proposal: the next time the applications queues a CAPTURE buffer it is returned
> at once as an empty buffer with FLAG_LAST set.
>
SGTM. It's actually similar to a relatively common case where all
CAPTURE buffers have been dequeued and the application has to refill
the CAPTURE queue, but in the meantime a drain request needs to be
issued.
> 2) Both queues are streaming and buffers have been encoded, but currently no buffers
> are queued on either vb2_queue. Now ENC_CMD_STOP is issued. What should happen?
>
> Proposal: the next time the applications queues a CAPTURE buffer it is returned
> at once as an empty buffer with FLAG_LAST set. This is consistent with the
> previous corner case.
Agreed.
>
> 3) The CAPTURE queue contains buffers, the OUTPUT queue does not. Now ENC_CMD_STOP
> is issued. What should happen?
>
> Proposal: the oldest CAPTURE buffer in the ready queue is returned as an empty
> buffer with FLAG_LAST set.
Generally agreed, but not sure if there is a reason to specifically
refer to the oldest buffer. (I'm personally for keeping the queues
ordered, though...)
>
> 4) Both queues have queued buffers. ENC_CMD_STOP is issued to start the drain process.
> Before the drain process completes STREAMOFF is called for either CAPTURE or
> OUTPUT queue. What should happen?
>
> Proposal for STREAMOFF(CAPTURE): aborts the drain process and all CAPTURE buffers are
> returned to userspace. If encoding is restarted, then any remaining OUTPUT buffers
> will be used as input to the encoder.
>
Agreed.
> Proposal for STREAMOFF(OUTPUT): the next capture buffer will be empty and have
> FLAG_LAST set.
Agreed.
>
> Some of this might have to be documented, but these corner cases should certainly be
> tested by v4l2-compliance. Before I write those tests I'd like to know if you agree
> with this.
Agreed with just one minor comment. Thanks for checking with me!
Best regards,
Tomasz

On Tue, Mar 26, 2019 at 1:33 AM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>
> On 3/25/19 2:12 PM, Hans Verkuil wrote:
> > Another comment found while creating compliance tests:
> >
> > On 1/24/19 11:04 AM, Tomasz Figa wrote:
> >> +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 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 decoded 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,
> >
> > I assume that calling CMD_START when *not* draining will succeed but does nothing.
> >
> > In other words: while draining is in progress START will return EBUSY. When draining
> > was finished, then START will resume the encoder. In all other cases it just returns
> > 0 since the encoder is really already started.
> >
> >> +
> >> + * 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.
> >
> > I assume calling STOP again once the drain sequence completed just returns 0 and
> > doesn't do anything else (since we're already stopped).
> >
> >> +
> >> + Although mandatory, the availability of encoder commands may be queried
> >> + using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
> >
> > Some corner cases:
> >
> > 1) No buffers are queued on either vb2_queue, but STREAMON is called for both queues.
> > Now ENC_CMD_STOP is issued. What should happen?
> >
> > Proposal: the next time the applications queues a CAPTURE buffer it is returned
> > at once as an empty buffer with FLAG_LAST set.
> >
> > 2) Both queues are streaming and buffers have been encoded, but currently no buffers
> > are queued on either vb2_queue. Now ENC_CMD_STOP is issued. What should happen?
> >
> > Proposal: the next time the applications queues a CAPTURE buffer it is returned
> > at once as an empty buffer with FLAG_LAST set. This is consistent with the
> > previous corner case.
> >
> > 3) The CAPTURE queue contains buffers, the OUTPUT queue does not. Now ENC_CMD_STOP
> > is issued. What should happen?
> >
> > Proposal: the oldest CAPTURE buffer in the ready queue is returned as an empty
> > buffer with FLAG_LAST set.
> >
> > 4) Both queues have queued buffers. ENC_CMD_STOP is issued to start the drain process.
> > Before the drain process completes STREAMOFF is called for either CAPTURE or
> > OUTPUT queue. What should happen?
> >
> > Proposal for STREAMOFF(CAPTURE): aborts the drain process and all CAPTURE buffers are
> > returned to userspace. If encoding is restarted, then any remaining OUTPUT buffers
> > will be used as input to the encoder.
> >
> > Proposal for STREAMOFF(OUTPUT): the next capture buffer will be empty and have
> > FLAG_LAST set.
>
> Note: I'm not quite sure about that last one yet. It's a bit tricky to implement.
>
> I think some of these rules might have to be implemented in v4l2-mem2mem.c to
> simplify drivers.
Most of the drivers would implement drain as a fake buffer inserted
into the driver-internal queue of source buffers. They also normally
have to iterate over the remaining buffers in that queue when
.stop_streaming() is called. If they find the fake buffer there, they
should return an empty buffer. The problematic case is when there is
no buffer in the CAPTURE queue. It would require the driver to
remember that the drain ended and check for that when next CAPTURE
buffer is queued. I guess that would converge with cases 1) and 2),
though.
Best regards,
Tomasz

On 4/8/19 10:36 AM, Tomasz Figa wrote:
> On Mon, Mar 25, 2019 at 10:12 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>
>> Another comment found while creating compliance tests:
>>
>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>>> +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 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 decoded 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,
>>
>> I assume that calling CMD_START when *not* draining will succeed but does nothing.
>>
>> In other words: while draining is in progress START will return EBUSY. When draining
>> was finished, then START will resume the encoder. In all other cases it just returns
>> 0 since the encoder is really already started.
>>
>
> Yes, that was the intention and seems to be the closest to the
> behavior described in the existing documentation.
>
>>> +
>>> + * 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.
>>
>> I assume calling STOP again once the drain sequence completed just returns 0 and
>> doesn't do anything else (since we're already stopped).
>>
>
> Right.
>
>>> +
>>> + Although mandatory, the availability of encoder commands may be queried
>>> + using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
>>
>> Some corner cases:
>>
>> 1) No buffers are queued on either vb2_queue, but STREAMON is called for both queues.
>> Now ENC_CMD_STOP is issued. What should happen?
>>
>> Proposal: the next time the applications queues a CAPTURE buffer it is returned
>> at once as an empty buffer with FLAG_LAST set.
>>
>
> SGTM. It's actually similar to a relatively common case where all
> CAPTURE buffers have been dequeued and the application has to refill
> the CAPTURE queue, but in the meantime a drain request needs to be
> issued.
>
>> 2) Both queues are streaming and buffers have been encoded, but currently no buffers
>> are queued on either vb2_queue. Now ENC_CMD_STOP is issued. What should happen?
>>
>> Proposal: the next time the applications queues a CAPTURE buffer it is returned
>> at once as an empty buffer with FLAG_LAST set. This is consistent with the
>> previous corner case.
>
> Agreed.
>
>>
>> 3) The CAPTURE queue contains buffers, the OUTPUT queue does not. Now ENC_CMD_STOP
>> is issued. What should happen?
>>
>> Proposal: the oldest CAPTURE buffer in the ready queue is returned as an empty
>> buffer with FLAG_LAST set.
>
> Generally agreed, but not sure if there is a reason to specifically
> refer to the oldest buffer. (I'm personally for keeping the queues
> ordered, though...)
Feel free to rephrase. Perhaps: "an empty CAPTURE buffer with FLAG_LAST set should be
queued up for userspace to signal that the encoder has stopped." Or something along
those lines.
Regards,
Hans
>
>>
>> 4) Both queues have queued buffers. ENC_CMD_STOP is issued to start the drain process.
>> Before the drain process completes STREAMOFF is called for either CAPTURE or
>> OUTPUT queue. What should happen?
>>
>> Proposal for STREAMOFF(CAPTURE): aborts the drain process and all CAPTURE buffers are
>> returned to userspace. If encoding is restarted, then any remaining OUTPUT buffers
>> will be used as input to the encoder.
>>
>
> Agreed.
>
>> Proposal for STREAMOFF(OUTPUT): the next capture buffer will be empty and have
>> FLAG_LAST set.
>
> Agreed.
>
>>
>> Some of this might have to be documented, but these corner cases should certainly be
>> tested by v4l2-compliance. Before I write those tests I'd like to know if you agree
>> with this.
>
> Agreed with just one minor comment. Thanks for checking with me!
>
> Best regards,
> Tomasz
>

On 4/8/19 11:23 AM, Tomasz Figa wrote:
> On Fri, Apr 5, 2019 at 7:03 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>
>> On 4/5/19 10:12 AM, Tomasz Figa wrote:
>>> On Thu, Mar 14, 2019 at 10:57 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>>>
>>>> Hi Tomasz,
>>>>
>>>> Some more comments...
>>>>
>>>> On 1/29/19 2:52 PM, Hans Verkuil wrote:
>>>>> Hi Tomasz,
>>>>>
>>>>> Some comments below. Nothing major, so I think a v4 should be ready to be
>>>>> merged.
>>>>>
>>>>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>>>>>> 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>
>>>>>> ---
>>>>>> Documentation/media/uapi/v4l/dev-encoder.rst | 586 ++++++++++++++++++
>>>>>> 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 | 38 +-
>>>>>> 5 files changed, 617 insertions(+), 15 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..fb8b05a132ee
>>>>>> --- /dev/null
>>>>>> +++ b/Documentation/media/uapi/v4l/dev-encoder.rst
>>>>>> @@ -0,0 +1,586 @@
>>>>>> +.. -*- coding: utf-8; mode: rst -*-
>>>>>> +
>>>>>> +.. _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 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.
>>>>>> +
>>>>>> +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_DEC_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(CAPTURE)" ];
>>>>>> + Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
>>>>>> +
>>>>>> + Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ];
>>>>>> + Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
>>>>>> +
>>>>>> + Stopped -> Encoding [ label = "V4L2_DEC_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 (always zero)
>>>>>> +
>>>>>> + other fields
>>>>>> + follow standard semantics
>>>>>> +
>>>>>> + * **Return fields:**
>>>>>> +
>>>>>> + ``sizeimage``
>>>>>> + adjusted size of ``CAPTURE`` buffers
>>>>>> +
>>>>>> + .. important::
>>>>>> +
>>>>>> + Changing the ``CAPTURE`` format may change the currently set ``OUTPUT``
>>>>>> + format. The encoder will derive a new ``OUTPUT`` format from the
>>>>>> + ``CAPTURE`` format being set, including resolution, colorimetry
>>>>>> + parameters, etc. If the client needs a specific ``OUTPUT`` format, it
>>>>>> + must adjust it afterwards.
>>>>>
>>>>> Hmm, "including resolution": if width and height are set to 0, what should the
>>>>> OUTPUT resolution be? Up to the driver? I think this should be clarified since
>>>>> at a first reading of this paragraph it appears to be contradictory.
>>>>
>>>> I think the driver should just return the width and height of the OUTPUT
>>>> format. So the width and height that userspace specifies is just ignored
>>>> and replaced by the width and height of the OUTPUT format. After all, that's
>>>> what the bitstream will encode. Returning 0 for width and height would make
>>>> this a strange exception in V4L2 and I want to avoid that.
>>>>
>>>
>>> Hmm, however, the width and height of the OUTPUT format is not what's
>>> actually encoded in the bitstream. The right selection rectangle
>>> determines that.
>>>
>>> In one of the previous versions I though we could put the codec
>
> s/codec/coded/...
>
>>> resolution as the width and height of the CAPTURE format, which would
>>> be the resolution of the encoded image rounded up to full macroblocks
>>> +/- some encoder-specific constraints. AFAIR there was some concern
>>> about OUTPUT format changes triggering CAPTURE format changes, but to
>>> be honest, I'm not sure if that's really a problem. I just decided to
>>> drop that for the simplicity.
>>
>> I'm not sure what your point is.
>>
>> The OUTPUT format has the coded resolution,
>
> That's not always true. The OUTPUT format is just the format of the
> source frame buffers. In special cases where the source resolution is
> nicely aligned, it would be the same as coded size, but the remaining
> cases are valid as well.
>
>> so when you set the
>> CAPTURE format it can just copy the OUTPUT coded resolution unless the
>> chosen CAPTURE pixelformat can't handle that in which case both the
>> OUTPUT and CAPTURE coded resolutions are clamped to whatever is the maximum
>> or minimum the codec is capable of.
>
> As per my comment above, generally speaking, the encoder will derive
> an appropriate coded format from the OUTPUT format, but also other
> factors, like the crop rectangles and possibly some internal
> constraints.
>
>>
>> That said, I am fine with just leaving it up to the driver as suggested
>> before. Just as long as both the CAPTURE and OUTPUT formats remain valid
>> (i.e. width and height may never be out of range).
>>
>
> Sounds good to me.
>
>>>
>>>>>
>>>>>> +
>>>>>> +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 by encoder to match alignment requirements, as
>>>>>> + required by the currently selected formats
>>>>>
>>>>> What if the width x height is larger than the maximum supported by the
>>>>> selected coded format? This should probably mention that in that case the
>>>>> width x height is reduced to the largest allowed value. Also mention that
>>>>> this maximum is reported by VIDIOC_ENUM_FRAMESIZES.
>>>>>
>>>>>> +
>>>>>> + other fields
>>>>>> + follow standard semantics
>>>>>> +
>>>>>> + * Setting the source resolution will reset the selection rectangles to their
>>>>>> + default values, based on the new resolution, as described in the step 5
>>>>>
>>>>> 5 -> 4
>>>>>
>>>>> Or just say: "as described in the next step."
>>>>>
>>>>>> + below.
>>>>
>>>> It should also be made explicit that:
>>>>
>>>> 1) the crop rectangle will be set to the given width and height *before*
>>>> it is being adjusted by S_FMT.
>>>>
>>>
>>> I don't think that's what we want here.
>>>
>>> Defining the default rectangle to be exactly the same as the OUTPUT
>>> resolution (after the adjustment) makes the semantics consistent - not
>>> setting the crop rectangle gives you exactly the behavior as if there
>>> was no cropping involved (or supported by the encoder).
>>
>> I think you are right. This seems to be what the coda driver does as well.
>> It is convenient to be able to just set a 1920x1080 format and have that
>> resolution be stored as the crop rectangle, since it avoids having to call
>> s_selection afterwards, but it is not really consistent with the way V4L2
>> works.
>>
>>>
>>>> Open question: should we support a compose rectangle for the CAPTURE that
>>>> is the same as the OUTPUT crop rectangle? I.e. the CAPTURE format contains
>>>> the adjusted width and height and the compose rectangle (read-only) contains
>>>> the visible width and height. It's not strictly necessary, but it is
>>>> symmetrical.
>>>
>>> Wouldn't it rather be the CAPTURE crop rectangle that would be of the
>>> same resolution of the OUTPUT compose rectangle? Then you could
>>> actually have the CAPTURE compose rectangle for putting that into the
>>> desired rectangle of the encoded stream, if the encoder supports that.
>>> (I don't know any that does, so probably out of concern for now.)
>>
>> Yes, you are right.
>>
>> But should we support this?
>>
>> I actually think not for this initial version. It can be added later, I guess.
>>
>
> I think it boils down on whether adding it later wouldn't
> significantly complicate the application logic. It also relates to my
> other comment somewhere below.
>
>>>
>>>>
>>>> 2) the CAPTURE format will be updated as well with the new OUTPUT width and
>>>> height. The CAPTURE sizeimage might change as well.
>>>>
>>>>>> +
>>>>>> +4. **Optional.** Set the visible resolution for the stream metadata via
>>>>>> + :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue.
>>>>
>>>> I think you should mention that this is only necessary if the crop rectangle
>>>> that is set when you set the format isn't what you want.
>>>>
>>>
>>> Ack.
>>>
>>>>>> +
>>>>>> + * **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.
>>>>
>>>> This last sentence contradicts the proposed behavior of S_FMT(OUTPUT).
>>>>
>>>
>>> Sorry, which part exactly and what part of the proposal exactly? :)
>>> (My comment above might be related, though.)
>>
>> Ignore my comment. We go back to explicitly requiring userspace to set the OUTPUT
>> crop selection target, so this note remains valid.
>>
>
> Ack.
>
>>>
>>>>>> +
>>>>>> + ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
>>>>>> + maximum rectangle within the coded resolution, which the cropped
>>>>>> + source frame can be composed into; if the hardware does not support
>>>>>> + composition or scaling, then this is always equal to the rectangle of
>>>>>> + width and height matching ``V4L2_SEL_TGT_CROP`` and located at (0, 0)
>>>>>> +
>>>>>> + ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
>>>>>> + equal to a rectangle of width and height matching
>>>>>> + ``V4L2_SEL_TGT_CROP`` and located at (0, 0)
>>>>>> +
>>>>>> + ``V4L2_SEL_TGT_COMPOSE``
>>>>>> + rectangle within the coded frame, which the cropped source frame
>>>>>> + is to be composed into; defaults to
>>>>>> + ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; read-only on hardware without
>>>>>> + additional compose/scaling capabilities; resulting stream will
>>>>>> + have this rectangle encoded as the visible rectangle in its
>>>>>> + metadata
>>>>
>>>> I think the compose targets for OUTPUT are only needed if the hardware can
>>>> actually do scaling and/or composition. Otherwise they can (must?) be
>>>> dropped.
>>>>
>>>
>>> Note that V4L2_SEL_TGT_COMPOSE is defined to be the way for the
>>> userspace to learn the target visible rectangle that's going to be
>>> encoded in the stream metadata. If we omit it, we wouldn't have a way
>>> that would be consistent between encoders that can do
>>> scaling/composition and those that can't.
>>
>> I'm not convinced about this. The standard API behavior is not to expose
>> functionality that the hardware can't do. So if scaling isn't possible on
>> the OUTPUT side, then it shouldn't expose OUTPUT compose rectangles.
>>
>> I also believe it very unlikely that we'll see encoders capable of scaling
>> as it doesn't make much sense.
>
> It does make a lot of sense - WebRTC requires 3 different sizes of the
> stream to be encoded at the same time. However, unfortunately, I
> haven't yet seen an encoder capable of doing so.
>
>> I would prefer to drop this to simplify the
>> spec, and when we get encoders that can scale, then we can add support for
>> compose rectangles (and I'm sure we'll need to think about how that
>> influences the CAPTURE side as well).
>>
>> For encoders without scaling it is the OUTPUT crop rectangle that defines
>> the visible rectangle.
>>
>>>
>>> However, with your proposal of actually having selection rectangles
>>> for the CAPTURE queue, it could be solved indeed. The OUTPUT queue
>>> would expose a varying set of rectangles, depending on the hardware
>>> capability, while the CAPTURE queue would always expose its rectangle
>>> with that information.
>>
>> I think we should keep it simple and only define selection rectangles
>> when really needed.
>>
>> So encoders support CROP on the OUTPUT, and decoders support CAPTURE
>> COMPOSE (may be read-only). Nothing else.
>>
>> Once support for scaling is needed (either on the encoder or decoder
>> side), then the spec should be enhanced. But I prefer to postpone that
>> until we actually have hardware that needs this.
>>
>
> Okay, let's do it this way then. Actually, I don't even think there is
> much value in exposing information internal to the bitstream metadata
> like this, similarly to the coded size. My intention was to just
> ensure that we can easily add scaling/composing functionality later.
>
> I just removed the COMPOSE rectangles from my next draft.
I don't think that supporting scaling will be a problem for the API as
such, since this is supported for standard video capture devices. It
just gets very complicated trying to describe how to configure all this.
So I prefer to avoid this until we need to.
>
> [snip]
>>>
>>>>
>>>> Changing the OUTPUT format will always fail if OUTPUT buffers are already allocated,
>>>> or if changing the OUTPUT format would change the CAPTURE format (sizeimage in
>>>> particular) and CAPTURE buffers were already allocated and are too small.
>>>
>>> The OUTPUT format must not change the CAPTURE format by definition.
>>> Otherwise we end up in a situation where we can't commit, because both
>>> queue formats can affect each other. Any change to the OUTPUT format
>>> that wouldn't work with the current CAPTURE format should be adjusted
>>> by the driver to match the current CAPTURE format.
>>
>> But the CAPTURE format *does* depend on the OUTPUT format: if the output
>> resolution changes, then so does the CAPTURE resolution and esp. the
>> sizeimage value, since that is typically resolution dependent.
>>
>> The coda driver does this as well: changing the output resolution
>> will update the capture resolution and sizeimage. The vicodec driver does the
>> same.
>>
>> Setting the CAPTURE format basically just selects the codec to use, after
>> that you can set the OUTPUT format and read the updated CAPTURE format to
>> get the new sizeimage value. In fact, setting the CAPTURE format shouldn't
>> change the OUTPUT format, unless the OUTPUT format is incompatible with the
>> newly selected codec.
>
> Let me think about it for a while.
Sleep on it, always works well for me :-)
Regards,
Hans

On Mon, Apr 8, 2019 at 5:43 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>
> On 4/8/19 10:36 AM, Tomasz Figa wrote:
> > On Mon, Mar 25, 2019 at 10:12 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
> >>
> >> Another comment found while creating compliance tests:
> >>
> >> On 1/24/19 11:04 AM, Tomasz Figa wrote:
> >>> +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 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 decoded 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,
> >>
> >> I assume that calling CMD_START when *not* draining will succeed but does nothing.
> >>
> >> In other words: while draining is in progress START will return EBUSY. When draining
> >> was finished, then START will resume the encoder. In all other cases it just returns
> >> 0 since the encoder is really already started.
> >>
> >
> > Yes, that was the intention and seems to be the closest to the
> > behavior described in the existing documentation.
> >
> >>> +
> >>> + * 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.
> >>
> >> I assume calling STOP again once the drain sequence completed just returns 0 and
> >> doesn't do anything else (since we're already stopped).
> >>
> >
> > Right.
> >
> >>> +
> >>> + Although mandatory, the availability of encoder commands may be queried
> >>> + using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
> >>
> >> Some corner cases:
> >>
> >> 1) No buffers are queued on either vb2_queue, but STREAMON is called for both queues.
> >> Now ENC_CMD_STOP is issued. What should happen?
> >>
> >> Proposal: the next time the applications queues a CAPTURE buffer it is returned
> >> at once as an empty buffer with FLAG_LAST set.
> >>
> >
> > SGTM. It's actually similar to a relatively common case where all
> > CAPTURE buffers have been dequeued and the application has to refill
> > the CAPTURE queue, but in the meantime a drain request needs to be
> > issued.
> >
> >> 2) Both queues are streaming and buffers have been encoded, but currently no buffers
> >> are queued on either vb2_queue. Now ENC_CMD_STOP is issued. What should happen?
> >>
> >> Proposal: the next time the applications queues a CAPTURE buffer it is returned
> >> at once as an empty buffer with FLAG_LAST set. This is consistent with the
> >> previous corner case.
> >
> > Agreed.
> >
> >>
> >> 3) The CAPTURE queue contains buffers, the OUTPUT queue does not. Now ENC_CMD_STOP
> >> is issued. What should happen?
> >>
> >> Proposal: the oldest CAPTURE buffer in the ready queue is returned as an empty
> >> buffer with FLAG_LAST set.
> >
> > Generally agreed, but not sure if there is a reason to specifically
> > refer to the oldest buffer. (I'm personally for keeping the queues
> > ordered, though...)
>
> Feel free to rephrase. Perhaps: "an empty CAPTURE buffer with FLAG_LAST set should be
> queued up for userspace to signal that the encoder has stopped." Or something along
> those lines.
I've added a note:
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 cancelled and all
``CAPTURE`` buffers are implicitly returned to the userpace.
* 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.
Slightly changed the split into cases to cover behaviors rather than
conditions. WDYT?
Best regards,
Tomasz
>
> Regards,
>
> Hans
>
> >
> >>
> >> 4) Both queues have queued buffers. ENC_CMD_STOP is issued to start the drain process.
> >> Before the drain process completes STREAMOFF is called for either CAPTURE or
> >> OUTPUT queue. What should happen?
> >>
> >> Proposal for STREAMOFF(CAPTURE): aborts the drain process and all CAPTURE buffers are
> >> returned to userspace. If encoding is restarted, then any remaining OUTPUT buffers
> >> will be used as input to the encoder.
> >>
> >
> > Agreed.
> >
> >> Proposal for STREAMOFF(OUTPUT): the next capture buffer will be empty and have
> >> FLAG_LAST set.
> >
> > Agreed.
> >
> >>
> >> Some of this might have to be documented, but these corner cases should certainly be
> >> tested by v4l2-compliance. Before I write those tests I'd like to know if you agree
> >> with this.
> >
> > Agreed with just one minor comment. Thanks for checking with me!
> >
> > Best regards,
> > Tomasz
> >
>

On 4/9/19 9:11 AM, Tomasz Figa wrote:
> On Mon, Apr 8, 2019 at 5:43 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>
>> On 4/8/19 10:36 AM, Tomasz Figa wrote:
>>> On Mon, Mar 25, 2019 at 10:12 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>>>
>>>> Another comment found while creating compliance tests:
>>>>
>>>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>>>>> +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 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 decoded 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,
>>>>
>>>> I assume that calling CMD_START when *not* draining will succeed but does nothing.
>>>>
>>>> In other words: while draining is in progress START will return EBUSY. When draining
>>>> was finished, then START will resume the encoder. In all other cases it just returns
>>>> 0 since the encoder is really already started.
>>>>
>>>
>>> Yes, that was the intention and seems to be the closest to the
>>> behavior described in the existing documentation.
>>>
>>>>> +
>>>>> + * 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.
>>>>
>>>> I assume calling STOP again once the drain sequence completed just returns 0 and
>>>> doesn't do anything else (since we're already stopped).
>>>>
>>>
>>> Right.
>>>
>>>>> +
>>>>> + Although mandatory, the availability of encoder commands may be queried
>>>>> + using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
>>>>
>>>> Some corner cases:
>>>>
>>>> 1) No buffers are queued on either vb2_queue, but STREAMON is called for both queues.
>>>> Now ENC_CMD_STOP is issued. What should happen?
>>>>
>>>> Proposal: the next time the applications queues a CAPTURE buffer it is returned
>>>> at once as an empty buffer with FLAG_LAST set.
>>>>
>>>
>>> SGTM. It's actually similar to a relatively common case where all
>>> CAPTURE buffers have been dequeued and the application has to refill
>>> the CAPTURE queue, but in the meantime a drain request needs to be
>>> issued.
>>>
>>>> 2) Both queues are streaming and buffers have been encoded, but currently no buffers
>>>> are queued on either vb2_queue. Now ENC_CMD_STOP is issued. What should happen?
>>>>
>>>> Proposal: the next time the applications queues a CAPTURE buffer it is returned
>>>> at once as an empty buffer with FLAG_LAST set. This is consistent with the
>>>> previous corner case.
>>>
>>> Agreed.
>>>
>>>>
>>>> 3) The CAPTURE queue contains buffers, the OUTPUT queue does not. Now ENC_CMD_STOP
>>>> is issued. What should happen?
>>>>
>>>> Proposal: the oldest CAPTURE buffer in the ready queue is returned as an empty
>>>> buffer with FLAG_LAST set.
>>>
>>> Generally agreed, but not sure if there is a reason to specifically
>>> refer to the oldest buffer. (I'm personally for keeping the queues
>>> ordered, though...)
>>
>> Feel free to rephrase. Perhaps: "an empty CAPTURE buffer with FLAG_LAST set should be
>> queued up for userspace to signal that the encoder has stopped." Or something along
>> those lines.
>
> I've added a note:
>
> 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 cancelled and all
cancelled -> canceled
> ``CAPTURE`` buffers are implicitly returned to the userpace.
userpace -> userspace
>
> * 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.
>
> Slightly changed the split into cases to cover behaviors rather than
> conditions. WDYT?
Looks good (with those two typos fixed).
Hans
>
> Best regards,
> Tomasz
>
>>
>> Regards,
>>
>> Hans
>>
>>>
>>>>
>>>> 4) Both queues have queued buffers. ENC_CMD_STOP is issued to start the drain process.
>>>> Before the drain process completes STREAMOFF is called for either CAPTURE or
>>>> OUTPUT queue. What should happen?
>>>>
>>>> Proposal for STREAMOFF(CAPTURE): aborts the drain process and all CAPTURE buffers are
>>>> returned to userspace. If encoding is restarted, then any remaining OUTPUT buffers
>>>> will be used as input to the encoder.
>>>>
>>>
>>> Agreed.
>>>
>>>> Proposal for STREAMOFF(OUTPUT): the next capture buffer will be empty and have
>>>> FLAG_LAST set.
>>>
>>> Agreed.
>>>
>>>>
>>>> Some of this might have to be documented, but these corner cases should certainly be
>>>> tested by v4l2-compliance. Before I write those tests I'd like to know if you agree
>>>> with this.
>>>
>>> Agreed with just one minor comment. Thanks for checking with me!
>>>
>>> Best regards,
>>> Tomasz
>>>
>>

On Tue, Apr 9, 2019 at 6:37 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>
> On 4/9/19 9:11 AM, Tomasz Figa wrote:
> > On Mon, Apr 8, 2019 at 5:43 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
> >>
> >> On 4/8/19 10:36 AM, Tomasz Figa wrote:
> >>> On Mon, Mar 25, 2019 at 10:12 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
> >>>>
> >>>> Another comment found while creating compliance tests:
> >>>>
> >>>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
> >>>>> +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 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 decoded 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,
> >>>>
> >>>> I assume that calling CMD_START when *not* draining will succeed but does nothing.
> >>>>
> >>>> In other words: while draining is in progress START will return EBUSY. When draining
> >>>> was finished, then START will resume the encoder. In all other cases it just returns
> >>>> 0 since the encoder is really already started.
> >>>>
> >>>
> >>> Yes, that was the intention and seems to be the closest to the
> >>> behavior described in the existing documentation.
> >>>
> >>>>> +
> >>>>> + * 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.
> >>>>
> >>>> I assume calling STOP again once the drain sequence completed just returns 0 and
> >>>> doesn't do anything else (since we're already stopped).
> >>>>
> >>>
> >>> Right.
> >>>
> >>>>> +
> >>>>> + Although mandatory, the availability of encoder commands may be queried
> >>>>> + using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
> >>>>
> >>>> Some corner cases:
> >>>>
> >>>> 1) No buffers are queued on either vb2_queue, but STREAMON is called for both queues.
> >>>> Now ENC_CMD_STOP is issued. What should happen?
> >>>>
> >>>> Proposal: the next time the applications queues a CAPTURE buffer it is returned
> >>>> at once as an empty buffer with FLAG_LAST set.
> >>>>
> >>>
> >>> SGTM. It's actually similar to a relatively common case where all
> >>> CAPTURE buffers have been dequeued and the application has to refill
> >>> the CAPTURE queue, but in the meantime a drain request needs to be
> >>> issued.
> >>>
> >>>> 2) Both queues are streaming and buffers have been encoded, but currently no buffers
> >>>> are queued on either vb2_queue. Now ENC_CMD_STOP is issued. What should happen?
> >>>>
> >>>> Proposal: the next time the applications queues a CAPTURE buffer it is returned
> >>>> at once as an empty buffer with FLAG_LAST set. This is consistent with the
> >>>> previous corner case.
> >>>
> >>> Agreed.
> >>>
> >>>>
> >>>> 3) The CAPTURE queue contains buffers, the OUTPUT queue does not. Now ENC_CMD_STOP
> >>>> is issued. What should happen?
> >>>>
> >>>> Proposal: the oldest CAPTURE buffer in the ready queue is returned as an empty
> >>>> buffer with FLAG_LAST set.
> >>>
> >>> Generally agreed, but not sure if there is a reason to specifically
> >>> refer to the oldest buffer. (I'm personally for keeping the queues
> >>> ordered, though...)
> >>
> >> Feel free to rephrase. Perhaps: "an empty CAPTURE buffer with FLAG_LAST set should be
> >> queued up for userspace to signal that the encoder has stopped." Or something along
> >> those lines.
> >
> > I've added a note:
> >
> > 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 cancelled and all
>
> cancelled -> canceled
>
> > ``CAPTURE`` buffers are implicitly returned to the userpace.
>
> userpace -> userspace
>
Actually changed it to "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.
> >
> > Slightly changed the split into cases to cover behaviors rather than
> > conditions. WDYT?
>
> Looks good (with those two typos fixed).
>
Thanks.
> Hans
>
> >
> > Best regards,
> > Tomasz
> >
> >>
> >> Regards,
> >>
> >> Hans
> >>
> >>>
> >>>>
> >>>> 4) Both queues have queued buffers. ENC_CMD_STOP is issued to start the drain process.
> >>>> Before the drain process completes STREAMOFF is called for either CAPTURE or
> >>>> OUTPUT queue. What should happen?
> >>>>
> >>>> Proposal for STREAMOFF(CAPTURE): aborts the drain process and all CAPTURE buffers are
> >>>> returned to userspace. If encoding is restarted, then any remaining OUTPUT buffers
> >>>> will be used as input to the encoder.
> >>>>
> >>>
> >>> Agreed.
> >>>
> >>>> Proposal for STREAMOFF(OUTPUT): the next capture buffer will be empty and have
> >>>> FLAG_LAST set.
> >>>
> >>> Agreed.
> >>>
> >>>>
> >>>> Some of this might have to be documented, but these corner cases should certainly be
> >>>> tested by v4l2-compliance. Before I write those tests I'd like to know if you agree
> >>>> with this.
> >>>
> >>> Agreed with just one minor comment. Thanks for checking with me!
> >>>
> >>> Best regards,
> >>> Tomasz
> >>>
> >>
>

On 4/9/19 11:35 AM, Tomasz Figa wrote:
> On Mon, Apr 8, 2019 at 8:11 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>
>> On 4/8/19 11:23 AM, Tomasz Figa wrote:
>>> On Fri, Apr 5, 2019 at 7:03 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>>>
>>>> On 4/5/19 10:12 AM, Tomasz Figa wrote:
>>>>> On Thu, Mar 14, 2019 at 10:57 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>>>>>
>>>>>> Hi Tomasz,
>>>>>>
>>>>>> Some more comments...
>>>>>>
>>>>>> On 1/29/19 2:52 PM, Hans Verkuil wrote:
>>>>>>> Hi Tomasz,
>>>>>>>
>>>>>>> Some comments below. Nothing major, so I think a v4 should be ready to be
>>>>>>> merged.
>>>>>>>
>>>>>>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>>>>>>>> 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>
>>>>>>>> ---
>>>>>>>> Documentation/media/uapi/v4l/dev-encoder.rst | 586 ++++++++++++++++++
>>>>>>>> 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 | 38 +-
>>>>>>>> 5 files changed, 617 insertions(+), 15 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..fb8b05a132ee
>>>>>>>> --- /dev/null
>>>>>>>> +++ b/Documentation/media/uapi/v4l/dev-encoder.rst
>>>>>>>> @@ -0,0 +1,586 @@
>>>>>>>> +.. -*- coding: utf-8; mode: rst -*-
>>>>>>>> +
>>>>>>>> +.. _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 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.
>>>>>>>> +
>>>>>>>> +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_DEC_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(CAPTURE)" ];
>>>>>>>> + Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
>>>>>>>> +
>>>>>>>> + Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ];
>>>>>>>> + Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
>>>>>>>> +
>>>>>>>> + Stopped -> Encoding [ label = "V4L2_DEC_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 (always zero)
>>>>>>>> +
>>>>>>>> + other fields
>>>>>>>> + follow standard semantics
>>>>>>>> +
>>>>>>>> + * **Return fields:**
>>>>>>>> +
>>>>>>>> + ``sizeimage``
>>>>>>>> + adjusted size of ``CAPTURE`` buffers
>>>>>>>> +
>>>>>>>> + .. important::
>>>>>>>> +
>>>>>>>> + Changing the ``CAPTURE`` format may change the currently set ``OUTPUT``
>>>>>>>> + format. The encoder will derive a new ``OUTPUT`` format from the
>>>>>>>> + ``CAPTURE`` format being set, including resolution, colorimetry
>>>>>>>> + parameters, etc. If the client needs a specific ``OUTPUT`` format, it
>>>>>>>> + must adjust it afterwards.
>>>>>>>
>>>>>>> Hmm, "including resolution": if width and height are set to 0, what should the
>>>>>>> OUTPUT resolution be? Up to the driver? I think this should be clarified since
>>>>>>> at a first reading of this paragraph it appears to be contradictory.
>>>>>>
>>>>>> I think the driver should just return the width and height of the OUTPUT
>>>>>> format. So the width and height that userspace specifies is just ignored
>>>>>> and replaced by the width and height of the OUTPUT format. After all, that's
>>>>>> what the bitstream will encode. Returning 0 for width and height would make
>>>>>> this a strange exception in V4L2 and I want to avoid that.
>>>>>>
>>>>>
>>>>> Hmm, however, the width and height of the OUTPUT format is not what's
>>>>> actually encoded in the bitstream. The right selection rectangle
>>>>> determines that.
>>>>>
>>>>> In one of the previous versions I though we could put the codec
>>>
>>> s/codec/coded/...
>>>
>>>>> resolution as the width and height of the CAPTURE format, which would
>>>>> be the resolution of the encoded image rounded up to full macroblocks
>>>>> +/- some encoder-specific constraints. AFAIR there was some concern
>>>>> about OUTPUT format changes triggering CAPTURE format changes, but to
>>>>> be honest, I'm not sure if that's really a problem. I just decided to
>>>>> drop that for the simplicity.
>>>>
>>>> I'm not sure what your point is.
>>>>
>>>> The OUTPUT format has the coded resolution,
>>>
>>> That's not always true. The OUTPUT format is just the format of the
>>> source frame buffers. In special cases where the source resolution is
>>> nicely aligned, it would be the same as coded size, but the remaining
>>> cases are valid as well.
>>>
>>>> so when you set the
>>>> CAPTURE format it can just copy the OUTPUT coded resolution unless the
>>>> chosen CAPTURE pixelformat can't handle that in which case both the
>>>> OUTPUT and CAPTURE coded resolutions are clamped to whatever is the maximum
>>>> or minimum the codec is capable of.
>>>
>>> As per my comment above, generally speaking, the encoder will derive
>>> an appropriate coded format from the OUTPUT format, but also other
>>> factors, like the crop rectangles and possibly some internal
>>> constraints.
>>>
>>>>
>>>> That said, I am fine with just leaving it up to the driver as suggested
>>>> before. Just as long as both the CAPTURE and OUTPUT formats remain valid
>>>> (i.e. width and height may never be out of range).
>>>>
>>>
>>> Sounds good to me.
>>>
>>>>>
>>>>>>>
>>>>>>>> +
>>>>>>>> +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 by encoder to match alignment requirements, as
>>>>>>>> + required by the currently selected formats
>>>>>>>
>>>>>>> What if the width x height is larger than the maximum supported by the
>>>>>>> selected coded format? This should probably mention that in that case the
>>>>>>> width x height is reduced to the largest allowed value. Also mention that
>>>>>>> this maximum is reported by VIDIOC_ENUM_FRAMESIZES.
>>>>>>>
>>>>>>>> +
>>>>>>>> + other fields
>>>>>>>> + follow standard semantics
>>>>>>>> +
>>>>>>>> + * Setting the source resolution will reset the selection rectangles to their
>>>>>>>> + default values, based on the new resolution, as described in the step 5
>>>>>>>
>>>>>>> 5 -> 4
>>>>>>>
>>>>>>> Or just say: "as described in the next step."
>>>>>>>
>>>>>>>> + below.
>>>>>>
>>>>>> It should also be made explicit that:
>>>>>>
>>>>>> 1) the crop rectangle will be set to the given width and height *before*
>>>>>> it is being adjusted by S_FMT.
>>>>>>
>>>>>
>>>>> I don't think that's what we want here.
>>>>>
>>>>> Defining the default rectangle to be exactly the same as the OUTPUT
>>>>> resolution (after the adjustment) makes the semantics consistent - not
>>>>> setting the crop rectangle gives you exactly the behavior as if there
>>>>> was no cropping involved (or supported by the encoder).
>>>>
>>>> I think you are right. This seems to be what the coda driver does as well.
>>>> It is convenient to be able to just set a 1920x1080 format and have that
>>>> resolution be stored as the crop rectangle, since it avoids having to call
>>>> s_selection afterwards, but it is not really consistent with the way V4L2
>>>> works.
>>>>
>>>>>
>>>>>> Open question: should we support a compose rectangle for the CAPTURE that
>>>>>> is the same as the OUTPUT crop rectangle? I.e. the CAPTURE format contains
>>>>>> the adjusted width and height and the compose rectangle (read-only) contains
>>>>>> the visible width and height. It's not strictly necessary, but it is
>>>>>> symmetrical.
>>>>>
>>>>> Wouldn't it rather be the CAPTURE crop rectangle that would be of the
>>>>> same resolution of the OUTPUT compose rectangle? Then you could
>>>>> actually have the CAPTURE compose rectangle for putting that into the
>>>>> desired rectangle of the encoded stream, if the encoder supports that.
>>>>> (I don't know any that does, so probably out of concern for now.)
>>>>
>>>> Yes, you are right.
>>>>
>>>> But should we support this?
>>>>
>>>> I actually think not for this initial version. It can be added later, I guess.
>>>>
>>>
>>> I think it boils down on whether adding it later wouldn't
>>> significantly complicate the application logic. It also relates to my
>>> other comment somewhere below.
>>>
>>>>>
>>>>>>
>>>>>> 2) the CAPTURE format will be updated as well with the new OUTPUT width and
>>>>>> height. The CAPTURE sizeimage might change as well.
>>>>>>
>>>>>>>> +
>>>>>>>> +4. **Optional.** Set the visible resolution for the stream metadata via
>>>>>>>> + :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue.
>>>>>>
>>>>>> I think you should mention that this is only necessary if the crop rectangle
>>>>>> that is set when you set the format isn't what you want.
>>>>>>
>>>>>
>>>>> Ack.
>>>>>
>>>>>>>> +
>>>>>>>> + * **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.
>>>>>>
>>>>>> This last sentence contradicts the proposed behavior of S_FMT(OUTPUT).
>>>>>>
>>>>>
>>>>> Sorry, which part exactly and what part of the proposal exactly? :)
>>>>> (My comment above might be related, though.)
>>>>
>>>> Ignore my comment. We go back to explicitly requiring userspace to set the OUTPUT
>>>> crop selection target, so this note remains valid.
>>>>
>>>
>>> Ack.
>>>
>>>>>
>>>>>>>> +
>>>>>>>> + ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
>>>>>>>> + maximum rectangle within the coded resolution, which the cropped
>>>>>>>> + source frame can be composed into; if the hardware does not support
>>>>>>>> + composition or scaling, then this is always equal to the rectangle of
>>>>>>>> + width and height matching ``V4L2_SEL_TGT_CROP`` and located at (0, 0)
>>>>>>>> +
>>>>>>>> + ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
>>>>>>>> + equal to a rectangle of width and height matching
>>>>>>>> + ``V4L2_SEL_TGT_CROP`` and located at (0, 0)
>>>>>>>> +
>>>>>>>> + ``V4L2_SEL_TGT_COMPOSE``
>>>>>>>> + rectangle within the coded frame, which the cropped source frame
>>>>>>>> + is to be composed into; defaults to
>>>>>>>> + ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; read-only on hardware without
>>>>>>>> + additional compose/scaling capabilities; resulting stream will
>>>>>>>> + have this rectangle encoded as the visible rectangle in its
>>>>>>>> + metadata
>>>>>>
>>>>>> I think the compose targets for OUTPUT are only needed if the hardware can
>>>>>> actually do scaling and/or composition. Otherwise they can (must?) be
>>>>>> dropped.
>>>>>>
>>>>>
>>>>> Note that V4L2_SEL_TGT_COMPOSE is defined to be the way for the
>>>>> userspace to learn the target visible rectangle that's going to be
>>>>> encoded in the stream metadata. If we omit it, we wouldn't have a way
>>>>> that would be consistent between encoders that can do
>>>>> scaling/composition and those that can't.
>>>>
>>>> I'm not convinced about this. The standard API behavior is not to expose
>>>> functionality that the hardware can't do. So if scaling isn't possible on
>>>> the OUTPUT side, then it shouldn't expose OUTPUT compose rectangles.
>>>>
>>>> I also believe it very unlikely that we'll see encoders capable of scaling
>>>> as it doesn't make much sense.
>>>
>>> It does make a lot of sense - WebRTC requires 3 different sizes of the
>>> stream to be encoded at the same time. However, unfortunately, I
>>> haven't yet seen an encoder capable of doing so.
>>>
>>>> I would prefer to drop this to simplify the
>>>> spec, and when we get encoders that can scale, then we can add support for
>>>> compose rectangles (and I'm sure we'll need to think about how that
>>>> influences the CAPTURE side as well).
>>>>
>>>> For encoders without scaling it is the OUTPUT crop rectangle that defines
>>>> the visible rectangle.
>>>>
>>>>>
>>>>> However, with your proposal of actually having selection rectangles
>>>>> for the CAPTURE queue, it could be solved indeed. The OUTPUT queue
>>>>> would expose a varying set of rectangles, depending on the hardware
>>>>> capability, while the CAPTURE queue would always expose its rectangle
>>>>> with that information.
>>>>
>>>> I think we should keep it simple and only define selection rectangles
>>>> when really needed.
>>>>
>>>> So encoders support CROP on the OUTPUT, and decoders support CAPTURE
>>>> COMPOSE (may be read-only). Nothing else.
>>>>
>>>> Once support for scaling is needed (either on the encoder or decoder
>>>> side), then the spec should be enhanced. But I prefer to postpone that
>>>> until we actually have hardware that needs this.
>>>>
>>>
>>> Okay, let's do it this way then. Actually, I don't even think there is
>>> much value in exposing information internal to the bitstream metadata
>>> like this, similarly to the coded size. My intention was to just
>>> ensure that we can easily add scaling/composing functionality later.
>>>
>>> I just removed the COMPOSE rectangles from my next draft.
>>
>> I don't think that supporting scaling will be a problem for the API as
>> such, since this is supported for standard video capture devices. It
>> just gets very complicated trying to describe how to configure all this.
>>
>> So I prefer to avoid this until we need to.
>>
>>>
>>> [snip]
>>>>>
>>>>>>
>>>>>> Changing the OUTPUT format will always fail if OUTPUT buffers are already allocated,
>>>>>> or if changing the OUTPUT format would change the CAPTURE format (sizeimage in
>>>>>> particular) and CAPTURE buffers were already allocated and are too small.
>>>>>
>>>>> The OUTPUT format must not change the CAPTURE format by definition.
>>>>> Otherwise we end up in a situation where we can't commit, because both
>>>>> queue formats can affect each other. Any change to the OUTPUT format
>>>>> that wouldn't work with the current CAPTURE format should be adjusted
>>>>> by the driver to match the current CAPTURE format.
>>>>
>>>> But the CAPTURE format *does* depend on the OUTPUT format: if the output
>>>> resolution changes, then so does the CAPTURE resolution and esp. the
>>>> sizeimage value, since that is typically resolution dependent.
>>>>
>>>> The coda driver does this as well: changing the output resolution
>>>> will update the capture resolution and sizeimage. The vicodec driver does the
>>>> same.
>>>>
>>>> Setting the CAPTURE format basically just selects the codec to use, after
>>>> that you can set the OUTPUT format and read the updated CAPTURE format to
>>>> get the new sizeimage value. In fact, setting the CAPTURE format shouldn't
>>>> change the OUTPUT format, unless the OUTPUT format is incompatible with the
>>>> newly selected codec.
>>>
>>> Let me think about it for a while.
>>
>> Sleep on it, always works well for me :-)
>
> Okay, I think I'm not convinced.
>
> I believe we decided to allow sizeimage to be specified by the
> application, because it knows more about the stream it's going to
> encode. Only setting the size to 0 would make the encoder fall back to
> some simple internal heuristic.
Yes, that was the plan, but the patch stalled. I completely forgot
about this patch :-)
My last reply to "Re: [RFC PATCH] media/doc: Allow sizeimage to be set by
v4l clients" was March 14th.
Also, sizeimage must be at least the minimum size required for the given
CAPTURE width and height. So if it is less, then sizeimage will be set to that
minimum size.
>
> Another thing is handling resolution changes. I believe that would
> have to be handled by stopping the OUTPUT queue, changing the OUTPUT
> format and starting the OUTPUT queue, all that without stopping the
> CAPTURE queue. With the behavior you described it wouldn't work,
> because the OUTPUT format couldn't be changed.
>
> I'd suggest making OUTPUT format changes not change the CAPTURE sizeimage.
So OUTPUT format changes will still update the CAPTURE width and height?
It's kind of weird if you are encoding e.g. 1920x1080 but the CAPTURE format
says 1280x720. I'm not sure what is best.
What if the CAPTURE sizeimage is too small for the new OUTPUT resolution?
Should S_FMT(OUTPUT) fail with some error in that case?
Regards,
Hans
>
> Best regards,
> Tomasz
>

Le lundi 15 avril 2019 à 17:56 +0900, Tomasz Figa a écrit :
> > Sounds like we need something similar to the SOURCE_CHANGE event
> > mechanism if we want to allow dynamic bitrate control which would
> > require re-allocation of the capture buffer queue. (Or any other
> > runtime control on our encoders, which is really expected to be
> > supported these days).
>
> Sounds like it. Or we could just assume that one needs to stop both
> queues to do a resolution change, since most codes would anyway reset
> the stream (e.g. send PPS/SPS, etc. for H.264) to change the
> resolution. Not sure if that assumption always holds, though.
I think for resolution/profile/level changes you have a good point, as
you said, we need to start a new stream (new header, new IDR). Maybe
then we should simply require the driver to allocate enough buffer to
support the highest bitrate for the selected resoltion/profile/level?
Though, this could create situation where we waste a lot of memory. On
the other side, if you need to reallocate your buffers on bitrate
change, it might create a visible freeze.
Nicolas

On 5/22/19 10:43 AM, Tomasz Figa wrote:
> On Tue, Apr 9, 2019 at 6:43 PM Tomasz Figa <tfiga@chromium.org> wrote:
>>
>> On Tue, Apr 9, 2019 at 6:37 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>>
>>> On 4/9/19 9:11 AM, Tomasz Figa wrote:
>>>> On Mon, Apr 8, 2019 at 5:43 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>>>>
>>>>> On 4/8/19 10:36 AM, Tomasz Figa wrote:
>>>>>> On Mon, Mar 25, 2019 at 10:12 PM Hans Verkuil <hverkuil@xs4all.nl> wrote:
>>>>>>>
>>>>>>> Another comment found while creating compliance tests:
>>>>>>>
>>>>>>> On 1/24/19 11:04 AM, Tomasz Figa wrote:
>>>>>>>> +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 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 decoded 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,
>>>>>>>
>>>>>>> I assume that calling CMD_START when *not* draining will succeed but does nothing.
>>>>>>>
>>>>>>> In other words: while draining is in progress START will return EBUSY. When draining
>>>>>>> was finished, then START will resume the encoder. In all other cases it just returns
>>>>>>> 0 since the encoder is really already started.
>>>>>>>
>>>>>>
>>>>>> Yes, that was the intention and seems to be the closest to the
>>>>>> behavior described in the existing documentation.
>>>>>>
>>>>>>>> +
>>>>>>>> + * 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.
>>>>>>>
>>>>>>> I assume calling STOP again once the drain sequence completed just returns 0 and
>>>>>>> doesn't do anything else (since we're already stopped).
>>>>>>>
>>>>>>
>>>>>> Right.
>>>>>>
>>>>>>>> +
>>>>>>>> + Although mandatory, the availability of encoder commands may be queried
>>>>>>>> + using :c:func:`VIDIOC_TRY_ENCODER_CMD`.
>>>>>>>
>>>>>>> Some corner cases:
>>>>>>>
>>>>>>> 1) No buffers are queued on either vb2_queue, but STREAMON is called for both queues.
>>>>>>> Now ENC_CMD_STOP is issued. What should happen?
>>>>>>>
>>>>>>> Proposal: the next time the applications queues a CAPTURE buffer it is returned
>>>>>>> at once as an empty buffer with FLAG_LAST set.
>>>>>>>
>>>>>>
>>>>>> SGTM. It's actually similar to a relatively common case where all
>>>>>> CAPTURE buffers have been dequeued and the application has to refill
>>>>>> the CAPTURE queue, but in the meantime a drain request needs to be
>>>>>> issued.
>>>>>>
>>>>>>> 2) Both queues are streaming and buffers have been encoded, but currently no buffers
>>>>>>> are queued on either vb2_queue. Now ENC_CMD_STOP is issued. What should happen?
>>>>>>>
>>>>>>> Proposal: the next time the applications queues a CAPTURE buffer it is returned
>>>>>>> at once as an empty buffer with FLAG_LAST set. This is consistent with the
>>>>>>> previous corner case.
>>>>>>
>>>>>> Agreed.
>>>>>>
>>>>>>>
>>>>>>> 3) The CAPTURE queue contains buffers, the OUTPUT queue does not. Now ENC_CMD_STOP
>>>>>>> is issued. What should happen?
>>>>>>>
>>>>>>> Proposal: the oldest CAPTURE buffer in the ready queue is returned as an empty
>>>>>>> buffer with FLAG_LAST set.
>>>>>>
>>>>>> Generally agreed, but not sure if there is a reason to specifically
>>>>>> refer to the oldest buffer. (I'm personally for keeping the queues
>>>>>> ordered, though...)
>>>>>
>>>>> Feel free to rephrase. Perhaps: "an empty CAPTURE buffer with FLAG_LAST set should be
>>>>> queued up for userspace to signal that the encoder has stopped." Or something along
>>>>> those lines.
>>>>
>>>> I've added a note:
>>>>
>>>> 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 cancelled and all
>>>
>>> cancelled -> canceled
>>>
>>>> ``CAPTURE`` buffers are implicitly returned to the userpace.
>>>
>>> userpace -> userspace
>>>
>>
>> Actually changed it to "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.
>>>>
>>>> Slightly changed the split into cases to cover behaviors rather than
>>>> conditions. WDYT?
>>>
>>> Looks good (with those two typos fixed).
>>>
>>
>> Thanks.
>
> Hmm, we actually looked into implementing this in mtk-vcodec and
> handling of this corner case gets quite complicated. When stopping the
> streaming on OUTPUT, you may not have any available CAPTURE buffer, so
> you need to keep some extra state in the driver and check it in vb2
> .buf_queue for CAPTURE to return the first buffer and complete the
> drain.
>
> The general handling of drain would have to look like this:
> - VIDIOC_DECODER_CMD must check if a drain isn't already in progress
> and also whether the queues are streaming,
> - STREAMOFF(CAPTURE) needs to cancel any pending drain,
> - STREAMOFF(OUTPUT) needs to return a CAPTURE buffer with LAST set if
> there is one or postpone it until a buffer is queued,
> - QBUF(CAPTURE) must return the buffer instantly if such return was
> postponed by STREAMOFF(OUTPUT).
> - DQBUF(CAPTURE) of a buffer with the LAST flag set would finish the sequence.
>
> Sounds like we definitely need some generic code to handle this...
Yeah, I realized the same thing while implementing this for vicodec.
I started on adding generic support to v4l2-mem2mem.c, but then decided
to wait until we have agreement on this spec. From the point of view of
the application this all makes sense and it is easy to implement, but for
a driver (or v4l2-mem2mem.c) this is definitely more complex.
Regards,
Hans