[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…

Claude review: drm/fourcc: document format naming scheme

[Claude Code Review Bot]

Patch Review

**Typo (line 137 of the diff context):**

```
+ * - 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 be" → "It should not be"

---

**Cb/Cr digit reversal rule is backwards:**

```
+ * - The two other digits indicate bits for the Y channel. If the Cb channel
+ *   comes before Cr, the digits are reversed.
```

This is wrong when checked against Q410/Q401:
- `DRM_FORMAT_Q410` (`'Q','4','1','0'`) = YCbCr (Cb before Cr) — digits are "10" (normal/unreversed)
- `DRM_FORMAT_Q401` (`'Q','4','0','1'`) = YCrCb (Cr before Cb) — digits are "01" (reversed)

So Q410 with Cb-before-Cr has the **normal** digits, not reversed. The rule is inverted — it should read: "If the **Cr** channel comes before Cb, the digits are reversed."

---

**Sub-sampling digit scheme doesn't cover NV formats:**

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

This accurately describes P-series (P010→0=2x2, P210→2=2x1) and Q-series (Q410→4=none) formats. However, the NV family — the most common multi-planar YUV formats — uses a completely different scheme where the two trailing digits encode **bits-per-pixel** (NV12=12bpp, NV16=16bpp, NV24=24bpp), not "subsampling digit + Y-channel bits". While the "for the most part" qualifier hedges this, it might be worth explicitly noting that older multi-planar families (NV, YUV/YVU) predate and don't follow this convention, to avoid confusion.

---

**P030 exception to "Y channel bits" claim:**

```
+ * - The two other digits indicate bits for the Y channel.
```

P030 has digits "30" but its Y channel is 10-bit (it's a packed 3×10-bit format). P010/P012/P016 all fit the rule correctly. P030 is arguably just a naming oddity but is a notable exception within the very format family (P-series) that the scheme is supposed to describe.

---

**Underscore plane delimiter claim lacks examples:**

```
+ * An underscore "_" can be used to delimit planes.
```

I couldn't find any existing format in `drm_fourcc.h` that uses an underscore to delimit planes. `YUV420_8BIT` and `YUV420_10BIT` have underscores, but those separate the format type from the bit depth, not planes. If this is forward-looking guidance, it might be clearer stated as such.

---

**Minor observation — channel list completeness:**

The channel definitions are good. "D" for darkness (inverse brightness) is a nice touch documenting the D1/D2/D4/D8 formats. The single-channel "R" formats (R1, R2, R4, R8, R10, R12, R16) are covered by listing "R" as red.

---

**Overall**: The RGB naming scheme documentation is accurate and useful. The YUV section needs the Cb/Cr reversal rule fixed (it's currently stating the opposite of what the code shows) and the typo corrected. Consider acknowledging that NV-family formats use a different, older convention.

---
Generated by Claude Code Patch Reviewer

Claude review: drm/fourcc: document format naming scheme

[Claude Code Review Bot]

Overall Series Review

Subject: drm/fourcc: document format naming scheme
Author: Simon Ser <contact@emersion.fr>
Patches: 3
Reviewed: 2026-04-28T15:16:43.486341

---

This is a single documentation-only patch from Simon Ser that adds a naming scheme reference to `drm_fourcc.h`, explaining how format names and fourccs are structured. The motivation is solid — the existing header has hundreds of format definitions with no documentation explaining the naming conventions, making it hard for contributors to choose names for new formats.

The documentation is largely accurate for RGB formats but has a factual error in the YUV digit-reversal rule and a typo. The "for the most part" qualifier on the YUV section is appropriate given the many exceptions, but the NV family — arguably the most widely used multi-planar YUV format family — doesn't follow the described scheme at all, which deserves acknowledgment.

---
Generated by Claude Code Patch Reviewer