Re: [PATCH 4/7] media: uapi: v4l: Document source routes

Jacopo Mondi
2023-07-03T07:47:52Z

Hi Sakari

On Fri, Jun 30, 2023 at 11:43:35PM +0300, Sakari Ailus wrote:
> Document how internal pads are used on source routes.
>
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> ---
> .../userspace-api/media/v4l/dev-subdev.rst | 20 +++++++++++++++++++
> 1 file changed, 20 insertions(+)
>
> diff --git a/Documentation/userspace-api/media/v4l/dev-subdev.rst b/Documentation/userspace-api/media/v4l/dev-subdev.rst
> index a4f1df7093e8..5a46c9a9d352 100644
> --- a/Documentation/userspace-api/media/v4l/dev-subdev.rst
> +++ b/Documentation/userspace-api/media/v4l/dev-subdev.rst
> @@ -551,6 +551,26 @@ A stream at a specific point in the media pipeline is identified by the
> sub-device and a (pad, stream) pair. For sub-devices that do not support
> multiplexed streams the 'stream' field is always 0.
>
> +.. _v4l2-subdev-source-routes:
> +
> +Source routes
> +^^^^^^^^^^^^^

I always found the concept of source routes a bit confusing, should we
instead just present internal pads ?

> +
> +Cases where a single sub-device pad is a source of multiple streams are special
> +as there is no external sink pad for such a route. In those cases, the sources
> +of the streams are indicated by source routes that have an internal source pad
> +as the sink pad of such a route. Internal source pads have the
> +:ref:`MEDIA_PAD_FL_INTERNAL <MEDIA-PAD-FL-INTERNAL>` and ``MEDIA_PAD_FL_SINK``
> +pad flags set.

All this last part is a little bit hard to parse, not your fault but
the fact "internal source pads" are actually "SINK" pads is a bit
confusing ?

Can we remove the "source route" concept to avoid mixing source/sink ?

This can be rewritten as

Internal pads
^^^^^^^^^^^^^

Cases where a single sub-device pad is a source of multiple streams are special
as there is no external sink pad for such a route. A typical example is a
sensor device which produces a video stream and a metadata stream of
embedded data. To support such cases internal pads are introduced as
sink pads of such internally generated streams.
Internal source pads have the :ref:`MEDIA_PAD_FL_INTERNAL
<MEDIA-PAD-FL-INTERNAL>` and ``MEDIA_PAD_FL_SINK`` pad flags set.

> +Internal source pads have all the properties of a sink pad in such case,

Also here, "Internal source pads" are actually sinks :)

I would drop "source" from "Internal source pads"

> +including formats and selections. The format in this case is the source format
> +of the stream. An internal pad always has a single stream only (0).
> +
> +Generally source routes are not modifiable but they can be activated and

s/source routes/internal routes/ ?

> +deactivated using the :ref:`V4L2_SUBDEV_ROUTE_FL_ACTIVE
> +<v4l2-subdev-routing-flags>` flag, depending on driver capabilities.
> +
> Interaction between routes, streams, formats and selections
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> --
> 2.39.2
>