[PATCH] drm/fourcc: document format naming scheme

[PATCH] drm/fourcc: document format naming scheme

[Simon Ser]

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.
+ *
+ * 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.
+ * - The first digit indicates chroma sub-sampling: 0 for 2x2, 2 for 2x1, 4 for
+ *   none.
+ * - 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
  * ----------------
  *
-- 
2.54.0

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

[Laurent Pinchart]

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

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

[Simon Ser]

On Sunday, April 26th, 2026 at 18:47, Laurent Pinchart <laurent.pinchart@ideasonboard.com> wrote:

> > + * 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.

Right, that macro is almost never used… I see it only used for
XRGB1555 and RGB565. Someone recommended against using it, I don't
remember who.

See also:

 * Note that the DRM_FORMAT_BIG_ENDIAN flag should only be used in
 * case the format can't be specified otherwise, so we don't end up
 * with two values describing the same format.

> > + * - 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.

Yeah, but these use a completely different scheme, like the NV family.
And then there's single-plane YUV formats, which are just the wild west.
Not sure how to document all of that…

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

[Pekka Paalanen]

[-- Attachment #1: Type: text/plain, Size: 3555 bytes --]

On Sun, 26 Apr 2026 15:16:58 +0000
Simon Ser <contact@emersion.fr> 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.
> + *
> + * 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)

Hi,

"inverse relationship between channel value and luminance"

> + * - "Y", luma/brightness

"luma"

That is, I would avoid using the term brightness here.


Thanks,
pq

> + * - "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.
> + * - The first digit indicates chroma sub-sampling: 0 for 2x2, 2 for 2x1, 4 for
> + *   none.
> + * - 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
>   * ----------------
>   *


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Thomas Zimmermann]

Hi,

thanks for documenting this. See below for some proof reading.

Am 26.04.26 um 17:16 schrieb Simon Ser:
> 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

Rather use singular because there is only one format per buffer. And use 
active voice. Something like

'A format describes how to interpret a buffer and decode ...'

> + * values. Formats are uniquely identified by a four character code (fourcc).

'four-character code'

> + * Memory layout is always described in little-endian order.

Use active voice and at least hint to the big-endian flag. Something like:

"By default, a pixel's bytes are in little-endian order."

> + *
> + * 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.

Give some examples here. Something like:

"For example, XRGB8888 describes a pixel with 4 bytes. The first byte is 
unused and the trailing bytes contain red, green and blue channels 
respectively. R32F describes a pixel with a single red channel storing a 
32-bit floating-point value."


> + *
> + * 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.

'It is should not' -> "It should not" or "It must not" depending on the 
strictness of this rule.

> + * - The first digit indicates chroma sub-sampling: 0 for 2x2, 2 for 2x1, 4 for
> + *   none.
> + * - The two other digits indicate bits for the Y channel. If the Cb channel
> + *   comes before Cr, the digits are reversed.

Please give an example for a multi-planar format here.

> + *
> + * 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

'should try to' -> 'should'

Best regards
Thomas

> + * formats.
> + *
>    * Format Modifiers
>    * ----------------
>    *

-- 
--
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstr. 146, 90461 Nürnberg, Germany, www.suse.com
GF: Jochen Jaser, Andrew McDonald, Werner Knoblich, (HRB 36809, AG Nürnberg)