From: Ezequiel Garcia <ezequiel@collabora.com>
To: Tomasz Figa <tfiga@chromium.org>, linux-media@vger.kernel.org
Cc: linux-kernel@vger.kernel.org,
"Stanimir Varbanov" <stanimir.varbanov@linaro.org>,
"Mauro Carvalho Chehab" <mchehab@kernel.org>,
"Hans Verkuil" <hverkuil@xs4all.nl>,
"Pawel Osciak" <posciak@chromium.org>,
"Alexandre Courbot" <acourbot@chromium.org>,
kamil@wypas.org, a.hajda@samsung.com,
"Kyungmin Park" <kyungmin.park@samsung.com>,
jtp.park@samsung.com, "Philipp Zabel" <p.zabel@pengutronix.de>,
"Tiffany Lin (林慧珊)" <tiffany.lin@mediatek.com>,
"Andrew-CT Chen (陳智迪)" <andrew-ct.chen@mediatek.com>,
todor.tomov@linaro.org, nicolas@ndufresne.ca,
"Paul Kocialkowski" <paul.kocialkowski@bootlin.com>,
"Laurent Pinchart" <laurent.pinchart@ideasonboard.com>,
"Dave Stevenson" <dave.stevenson@raspberrypi.org>
Subject: Re: [PATCH 2/2] media: docs-rst: Document memory-to-memory video encoder interface
Date: Fri, 07 Sep 2018 17:17:03 -0300 [thread overview]
Message-ID: <19062a24c3aa2cb9e0410cf2884b4589e44c263b.camel@collabora.com> (raw)
In-Reply-To: <20180724140621.59624-3-tfiga@chromium.org>
On Tue, 2018-07-24 at 23:06 +0900, 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 | 550 +++++++++++++++++++
> Documentation/media/uapi/v4l/devices.rst | 1 +
> Documentation/media/uapi/v4l/v4l2.rst | 2 +
> 3 files changed, 553 insertions(+)
> 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..28be1698e99c
> --- /dev/null
> +++ b/Documentation/media/uapi/v4l/dev-encoder.rst
> @@ -0,0 +1,550 @@
> +.. -*- coding: utf-8; mode: rst -*-
> +
> +.. _encoder:
> +
> +****************************************
> +Memory-to-memory Video Encoder Interface
> +****************************************
> +
> +Input data to a video encoder are raw video frames in display order
> +to be encoded into the output bitstream. Output data are complete chunks of
> +valid bitstream, including all metadata, headers, etc. The resulting stream
> +must not need 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 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.
> +
> +3. All steps not marked “optional” are required.
> +
> +4. :c:func:`VIDIOC_G_EXT_CTRLS`, :c:func:`VIDIOC_S_EXT_CTRLS` may be used
> + interchangeably with :c:func:`VIDIOC_G_CTRL`, :c:func:`VIDIOC_S_CTRL`,
> + unless specified otherwise.
> +
> +5. Single-plane API (see spec) and applicable structures may be used
> + interchangeably with Multi-plane API, unless specified otherwise,
> + depending on driver 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. For ``OUTPUT`` buffer A, A’ represents a buffer on the ``CAPTURE`` queue
> + containing data (encoded frame/stream) that resulted from processing
> + buffer A.
> +
> +Glossary
> +========
> +
> +CAPTURE
> + the destination buffer queue; the queue of buffers containing encoded
> + bitstream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE```` or
> + ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data are captured from the
> + hardware into ``CAPTURE`` buffers
> +
> +client
> + application client communicating with the driver implementing this API
> +
> +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
> + coded format includes a feature of frame reordering; ``CAPTURE`` buffers
> + must be returned by the driver in decode order
> +
> +display order
> + the order in which frames must be displayed; ``OUTPUT`` buffers must be
> + queued by the client in display order
> +
> +IDR
> + 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. H264, VP8, VP9); codec-specific, but for most of
> + popular codecs the size is 16x16 samples (pixels)
> +
> +OUTPUT
> + the source buffer queue; 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 encoder; ``OUTPUT``
> +
> +source height
> + height in pixels for given source resolution
> +
> +source resolution
> + resolution in pixels of source frames being source to the encoder and
> + subject to further cropping to the bounds of visible resolution
> +
> +source width
> + width in pixels for given source resolution
> +
> +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
> +
> +Querying capabilities
> +=====================
> +
> +1. To enumerate the set of coded formats supported by the driver, the
> + client may call :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
> +
> + * The driver must always return the full set of supported formats,
> + irrespective of the format set on the ``OUTPUT`` queue.
> +
> +2. To enumerate the set of supported raw formats, the client may call
> + :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
> +
> + * The driver must return only the formats supported for the format
> + currently active on ``CAPTURE``.
> +
Paul and I where discussing about the default active format on CAPTURE
and OUTPUT queues. That is, the format that is active (if any) right
after driver probes.
Currently, the v4l2-compliance tool tests the default active format,
by requiring drivers to support:
fmt = g_fmt()
s_fmt(fmt)
Is this actually required? Should we also require this for stateful
and stateless codecs? If yes, should it be documented?
Regards,
Ezequiel
next prev parent reply other threads:[~2018-09-07 20:17 UTC|newest]
Thread overview: 62+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-07-24 14:06 [PATCH 0/2] Document memory-to-memory video codec interfaces Tomasz Figa
2018-07-24 14:06 ` [PATCH 1/2] media: docs-rst: Document memory-to-memory video decoder interface Tomasz Figa
2018-07-25 11:58 ` Hans Verkuil
2018-07-26 10:20 ` Tomasz Figa
2018-07-26 10:36 ` Philipp Zabel
2018-08-07 6:55 ` Tomasz Figa
2018-07-26 10:57 ` Hans Verkuil
2018-08-07 7:05 ` Tomasz Figa
2018-08-07 7:37 ` Hans Verkuil
2018-08-08 2:55 ` Tomasz Figa
2018-08-21 11:29 ` Stanimir Varbanov
2018-08-27 4:09 ` Tomasz Figa
2018-10-15 10:13 ` Tomasz Figa
2018-10-16 1:09 ` Nicolas Dufresne
2018-08-07 7:13 ` Hans Verkuil
2018-08-07 19:11 ` Maxime Jourdan
2018-08-08 3:07 ` Tomasz Figa
2018-08-08 7:19 ` Maxime Jourdan
2018-08-08 3:11 ` Tomasz Figa
2018-08-08 6:43 ` Hans Verkuil
2018-08-08 6:54 ` Ian Arkver
2018-09-19 10:17 ` Tomasz Figa
2018-10-08 12:22 ` Hans Verkuil
2018-10-09 4:23 ` Tomasz Figa
2018-10-09 6:39 ` Hans Verkuil
2018-07-30 12:52 ` Hans Verkuil
2018-08-07 7:08 ` Tomasz Figa
2018-08-08 2:46 ` Tomasz Figa
2018-08-20 13:04 ` Philipp Zabel
2018-08-20 13:12 ` Tomasz Figa
2018-08-20 14:13 ` Philipp Zabel
2018-08-20 14:27 ` Tomasz Figa
2018-08-20 15:33 ` Philipp Zabel
2018-08-27 4:03 ` Tomasz Figa
2018-08-31 8:26 ` Alexandre Courbot
2018-09-05 5:45 ` Tomasz Figa
2018-10-17 13:34 ` Laurent Pinchart
2018-10-18 10:03 ` Tomasz Figa
2018-10-18 11:22 ` Laurent Pinchart
2018-10-20 8:52 ` Tomasz Figa
2018-10-21 9:23 ` Laurent Pinchart
2018-10-22 6:19 ` Tomasz Figa
2018-10-20 10:24 ` Tomasz Figa
2018-10-21 9:26 ` Laurent Pinchart
2018-10-20 15:39 ` Tomasz Figa
2018-07-24 14:06 ` [PATCH 2/2] media: docs-rst: Document memory-to-memory video encoder interface Tomasz Figa
2018-07-25 13:41 ` Philipp Zabel
2018-08-07 6:07 ` Tomasz Figa
2018-07-25 13:57 ` Hans Verkuil
2018-08-07 6:54 ` Tomasz Figa
2018-08-07 7:25 ` Hans Verkuil
2018-10-16 7:36 ` Tomasz Figa
2018-10-16 13:49 ` Hans Verkuil
2018-10-22 4:50 ` Tomasz Figa
2018-09-07 20:17 ` Ezequiel Garcia [this message]
2018-09-10 3:34 ` Tomasz Figa
2018-10-17 15:19 ` Laurent Pinchart
2018-10-22 6:12 ` Tomasz Figa
2018-07-25 13:28 ` [PATCH 0/2] Document memory-to-memory video codec interfaces Philipp Zabel
2018-07-25 13:35 ` Tomasz Figa
2018-09-10 9:13 ` Hans Verkuil
2018-09-11 3:52 ` Tomasz Figa
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=19062a24c3aa2cb9e0410cf2884b4589e44c263b.camel@collabora.com \
--to=ezequiel@collabora.com \
--cc=a.hajda@samsung.com \
--cc=acourbot@chromium.org \
--cc=andrew-ct.chen@mediatek.com \
--cc=dave.stevenson@raspberrypi.org \
--cc=hverkuil@xs4all.nl \
--cc=jtp.park@samsung.com \
--cc=kamil@wypas.org \
--cc=kyungmin.park@samsung.com \
--cc=laurent.pinchart@ideasonboard.com \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=mchehab@kernel.org \
--cc=nicolas@ndufresne.ca \
--cc=p.zabel@pengutronix.de \
--cc=paul.kocialkowski@bootlin.com \
--cc=posciak@chromium.org \
--cc=stanimir.varbanov@linaro.org \
--cc=tfiga@chromium.org \
--cc=tiffany.lin@mediatek.com \
--cc=todor.tomov@linaro.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).