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

[Tomasz Figa]

Hi Stanimir,

On Mon, Oct 29, 2018 at 6:45 PM Stanimir Varbanov
<stanimir.varbanov@xxxxxxxxxx> wrote:
>
> Hi Tomasz,
>
> On 10/22/2018 05:48 PM, 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@xxxxxxxxxxxx>
> > ---
> >  Documentation/media/uapi/v4l/dev-decoder.rst  | 1082 +++++++++++++++++
> >  Documentation/media/uapi/v4l/devices.rst      |    1 +
> >  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, 1137 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..09c7a6621b8e
> > --- /dev/null
> > +++ b/Documentation/media/uapi/v4l/dev-decoder.rst
>
> <cut>
>
> > +Capture setup
> > +=============
> > +
>
> <cut>
>
> > +
> > +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
>
> Hans should correct me if I'm wrong but V4L2_SEL_TGT_CROP_xxx are
> applicable over OUTPUT queue type?

There is no such restriction. CROP selection targets of an OUTPUT
queue apply to the video stream read from the buffers, COMPOSE targets
of an OUTPUT queue apply to the output of the queue and input to the
processing block (hardware) in case of mem2mem devices, then CROP
targets of a CAPTURE queue apply to the output of the processing and
SELECTION targets of a CAPTURE queue apply to the stream written to
the buffers.

For a decoder, the OUTPUT stream is just a sequence of bytes, so
selection API doesn't apply to it. The processing (decoding) produces
a video stream and so the necessary selection capabilities are exposed
on the CAPTURE queue.

Best regards,
Tomasz