Re: [PATCH v4 1/4] media: uapi: Clarify MBUS color component order for serial buses

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

Hi Maxime,

Thank you for the patch.

On Mon, Oct 13, 2025 at 01:01:33PM +0200, Maxime Ripard wrote:
> The subdev format documentation has a subsection describing how to use
> the media bus pixel codes for serial buses. While it describes the
> sampling part well, it doesn't really describe the current convention
> used for the components order.
> 
> Let's improve that.

A long due improvement, thanks for working on it.

> Signed-off-by: Maxime Ripard <mripard@kernel.org>
> ---
>  Documentation/userspace-api/media/v4l/subdev-formats.rst | 14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst
> index 2a94371448dc07e5c7097421bd82f42dcd7e21aa..8e92f784abd8123f9ea950f954a60af56ee76dbe 100644
> --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst
> +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst
> @@ -158,16 +158,18 @@ formats in memory (a raw Bayer image won't be magically converted to
>  JPEG just by storing it to memory), there is no one-to-one
>  correspondence between them.
>  
>  The media bus pixel codes document parallel formats. Should the pixel data be
>  transported over a serial bus, the media bus pixel code that describes a
> -parallel format that transfers a sample on a single clock cycle is used. For
> -instance, both MEDIA_BUS_FMT_BGR888_1X24 and MEDIA_BUS_FMT_BGR888_3X8 are used
> -on parallel busses for transferring an 8 bits per sample BGR data, whereas on
> -serial busses the data in this format is only referred to using
> -MEDIA_BUS_FMT_BGR888_1X24. This is because there is effectively only a single
> -way to transport that format on the serial busses.
> +parallel format that transfers a sample on a single clock cycle is used. The
> +color component order used is the same used on the serial bus. For instance,
> +both MEDIA_BUS_FMT_BGR888_1X24 and MEDIA_BUS_FMT_BGR888_3X8 are used on parallel
> +busses for transferring an 8 bits per sample BGR data, whereas on serial busses
> +the data in this format is only referred to using MEDIA_BUS_FMT_BGR888_1X24,
> +with BGR meaning that the blue component is transmitted first, then green, then
> +red. This is because there is effectively only a single way to transport that
> +format on the serial busses.

I find this confusing. The text says that on serial buses
MEDIA_BUS_FMT_BGR888_1X24 is used, without mentioning this is an example
specific to CSI-2. Here's an attempt at improving the paragraph:


While the media bus pixel codes are named based on how pixels are transmitted on
parallel buses, serial buses do not define separate codes. By convention, they
use the codes that transfer a sample on a single clock cycle. and whose names
correspond to the order in which colour components are transmitted on the serial
bus. For instance, the MIPI CSI-2 24-bit RGB (RGB888) format uses the
MEDIA_BUS_FMT_BGR888_1X24 media bus code because CSI-2 transmits the blue colour
component first, followed by green and red. While used for 24-bit RGB data on
parallel buses, the MEDIA_BUS_FMT_BGR888_3X8 or MEDIA_BUS_FMT_RGB888_1X24 codes
must not be used for CSI-2.

>  
>  Packed RGB Formats
>  ^^^^^^^^^^^^^^^^^^
>  
>  Those formats transfer pixel data as red, green and blue components. The
> 

-- 
Regards,

Laurent Pinchart