[PATCH] drm/fourcc: document format naming scheme

[Simon Ser <contact@emersion.fr>]

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