Re: [PATCH 3/3] Documentation/media: rename "Codec Interface"

[Tomasz Figa <tfiga@chromium.org>]

Hi Hans,

On Tue, Jan 22, 2019 at 8:27 PM <hverkuil-cisco@xs4all.nl> wrote:
>
> From: Hans Verkuil <hverkuil-cisco@xs4all.nl>
>
> The "Codec Interface" chapter is poorly named since codecs are just one
> use-case of the Memory-to-Memory Interface. Rename it and clean up the
> text a bit.
>
> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> ---
>  .../media/uapi/mediactl/request-api.rst       |  4 ++--
>  .../v4l/{dev-codec.rst => dev-mem2mem.rst}    | 21 +++++++------------
>  Documentation/media/uapi/v4l/devices.rst      |  2 +-
>  .../media/uapi/v4l/pixfmt-compressed.rst      |  2 +-
>  Documentation/media/uapi/v4l/vidioc-qbuf.rst  |  2 +-
>  5 files changed, 13 insertions(+), 18 deletions(-)
>  rename Documentation/media/uapi/v4l/{dev-codec.rst => dev-mem2mem.rst} (79%)
>

Thanks for this cleanup! Indeed it makes much more sense with your
changes. Some comments inline.

> diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst
> index 4b25ad03f45a..1ad631e549fe 100644
> --- a/Documentation/media/uapi/mediactl/request-api.rst
> +++ b/Documentation/media/uapi/mediactl/request-api.rst
> @@ -91,7 +91,7 @@ A request must contain at least one buffer, otherwise ``ENOENT`` is returned.
>  A queued request cannot be modified anymore.
>
>  .. caution::
> -   For :ref:`memory-to-memory devices <codec>` you can use requests only for
> +   For :ref:`memory-to-memory devices <mem2mem>` you can use requests only for
>     output buffers, not for capture buffers. Attempting to add a capture buffer
>     to a request will result in an ``EACCES`` error.
>
> @@ -152,7 +152,7 @@ if it had just been allocated.
>  Example for a Codec Device
>  --------------------------
>
> -For use-cases such as :ref:`codecs <codec>`, the request API can be used
> +For use-cases such as :ref:`codecs <mem2mem>`, the request API can be used

I guess this should eventually be made to point to the codec sections.
Alex, perhaps it would make sense to do it in your documentation
patch.

>  to associate specific controls to
>  be applied by the driver for the OUTPUT buffer, allowing user-space
>  to queue many such buffers in advance. It can also take advantage of requests'
> diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> similarity index 79%
> rename from Documentation/media/uapi/v4l/dev-codec.rst
> rename to Documentation/media/uapi/v4l/dev-mem2mem.rst
> index b5e017c17834..69efcc747588 100644
> --- a/Documentation/media/uapi/v4l/dev-codec.rst
> +++ b/Documentation/media/uapi/v4l/dev-mem2mem.rst
> @@ -7,11 +7,11 @@
>  ..
>  .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
>
> -.. _codec:
> +.. _mem2mem:
>
> -***************
> -Codec Interface
> -***************
> +********************************
> +Video Memory To Memory Interface
> +********************************
>
>  A V4L2 codec can compress, decompress, transform, or otherwise convert

Codec still left here.

>  video data from one format into another format, in memory. Typically
> @@ -25,19 +25,14 @@ memory) stream I/O. An application will have to setup the stream I/O for
>  both sides and finally call :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
>  for both capture and output to start the codec.

Ditto.

>
> -Video compression codecs use the MPEG controls to setup their codec
> -parameters
> -
> -.. note::
> -
> -   The MPEG controls actually support many more codecs than
> -   just MPEG. See :ref:`mpeg-controls`.
> +Video compression codecs use codec controls to setup their codec parameters.
> +See :ref:`mpeg-controls`.
>
>  Memory-to-memory devices function as a shared resource: you can
>  open the video node multiple times, each application setting up their
> -own codec properties that are local to the file handle, and each can use
> +own properties that are local to the file handle, and each can use
>  it independently from the others. The driver will arbitrate access to
> -the codec and reprogram it whenever another file handler gets access.
> +the hardware and reprogram it whenever another file handler gets access.
>  This is different from the usual video node behavior where the video
>  properties are global to the device (i.e. changing something through one
>  file handle is visible through another file handle).
> diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
> index d6fcf3db5909..07f8d047662b 100644
> --- a/Documentation/media/uapi/v4l/devices.rst
> +++ b/Documentation/media/uapi/v4l/devices.rst
> @@ -21,7 +21,7 @@ Interfaces
>      dev-overlay
>      dev-output
>      dev-osd
> -    dev-codec
> +    dev-mem2mem
>      dev-raw-vbi
>      dev-sliced-vbi
>      dev-radio
> diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
> index e4c5e456df59..2675bef3eefe 100644
> --- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst
> +++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
> @@ -73,7 +73,7 @@ Compressed Formats
>        - 'MG2S'
>        - MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream.
>         This format is adapted for stateless video decoders that implement a
> -       MPEG-2 pipeline (using the :ref:`codec` and :ref:`media-request-api`).
> +       MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).

Reference to be updated later too.

Best regards,
Tomasz