Re: [PATCH] drm/fourcc: document format naming scheme

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

Hi Simon,

Thank you for the patch.

On Sun, Apr 26, 2026 at 03:16:58PM +0000, Simon Ser wrote:
> When adding a new format, one needs to pick a name and fourcc.
> This is not always an easy task: figuring out why current formats
> are named this way is tricky.
> 
> Document current practice to make that process easier.
> 
> See previous discussion at:
> https://lore.kernel.org/all/aocdbgbLe5WhUEOGeLg3P7fRDM8i72H9zBuUnoAjjsuvBLfMPofrPtaUEjII_43KXf1wCbv1G9UutJKMkWLaEcBSnrlUV78Wrhu6l_Z0xi8=@emersion.fr/
> 
> Signed-off-by: Simon Ser <contact@emersion.fr>
> Cc: Pekka Paalanen <ppaalanen@gmail.com>
> Cc: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
> Cc: Maxime Ripard <mripard@kernel.org>
> Cc: Thomas Zimmermann <tzimmermann@suse.de>
> Cc: David Airlie <airlied@gmail.com>
> Cc: Simona Vetter <simona@ffwll.ch>
> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> Cc: Dmitry Baryshkov <dmitry.baryshkov@oss.qualcomm.com>
> Cc: Daniel Stone <daniel@fooishbar.org>
> ---
>  include/uapi/drm/drm_fourcc.h | 39 +++++++++++++++++++++++++++++++++++
>  1 file changed, 39 insertions(+)
> 
> diff --git a/include/uapi/drm/drm_fourcc.h b/include/uapi/drm/drm_fourcc.h
> index ac66fa93b5a3..dc737c4fa5f2 100644
> --- a/include/uapi/drm/drm_fourcc.h
> +++ b/include/uapi/drm/drm_fourcc.h
> @@ -38,6 +38,45 @@ extern "C" {
>   * fourcc code, a Format Modifier may optionally be provided, in order to
>   * further describe the buffer's format - for example tiling or compression.
>   *
> + * Formats
> + * -------
> + *
> + * Formats describe how a buffer is interpreted to decode pixel color and alpha
> + * values. Formats are uniquely identified by a four character code (fourcc).
> + * Memory layout is always described in little-endian order.

This sentence may be a bit vague, especially given that we have the
DRM_FORMAT_BIG_ENDIAN() macro.

> + *
> + * The following channels are defined:
> + *
> + * - "R", red
> + * - "G", green
> + * - "B", blue
> + * - "A", alpha
> + * - "C", color index (for paletted formats)
> + * - "D", darkness (inverse relationship between channel value and brightness)
> + * - "Y", luma/brightness
> + * - "U", blue-difference chroma (Cb)
> + * - "V", red-difference chroma (Cr)
> + * - "X", a placeholder for undefined/unused contents
> + *
> + * Formats using the RGB color model have names made up of a list of channels
> + * followed by the number of bits used by each channel, respectively. Any
> + * padding is explicitly indicated by the special "X" channel. Channels use
> + * unsigned integers, except when suffixed by "F" to indicate IEEE 754 floats.
> + * An underscore "_" can be used to delimit planes.
> + *
> + * Multi-planar YUV formats use the following naming scheme for the most part:
> + *
> + * - The first letter indicates the number of planes, channel alignment and
> + *   ordering. It is should not be a letter already used to denote a channel.

s/It is/It/

> + * - The first digit indicates chroma sub-sampling: 0 for 2x2, 2 for 2x1, 4 for
> + *   none.

We also have 4x4 and 4x1 sub-sampled formats, it would be good to
document them.

> + * - The two other digits indicate bits for the Y channel. If the Cb channel
> + *   comes before Cr, the digits are reversed.
> + *
> + * Fourccs are allocated on a first-come, first-served basis. New format names
> + * and fourccs should try to use the same naming scheme as existing, similar
> + * formats.
> + *
>   * Format Modifiers
>   * ----------------
>   *

-- 
Regards,

Laurent Pinchart