Deprecate wl_drm, include GBM

docs/drm.md

@@ -1,14 +1,22 @@
 # DRM pixel formats
 
-The drm pixel formats follow the scheme:
+The DRM pixel formats follow the scheme:
 
     DRM_FORMAT_{component-format}
 
 The `component-format` part specifies the order and sizes of the components.
 All the components are listed first, optionally followed by their corresponding sizes
 in bits (e.g., `RGB888`, `YUVY`).
 
-There are a few categories of drm formats:
+The GBM pixel formats follow the scheme:
+
+    GBM_FORMAT_{component-format}
+
+GBM formats have the same names, enumeration values, interpretation, and meaning
+as DRM formats; this document uses DRM names, however the descriptions equally
+apply to GBM. There are however two special cases, described below.
+
+There are a few categories of DRM formats:
 
 * RGBA formats: `DRM_FORMAT_{rgba-componenent-format}`
 
@@ -54,6 +62,21 @@ There are a few categories of drm formats:
 
     Always stored as Y₀, U, Y₁, V in memory (Y₀ at lowest address, V at the highest)
 
+* GBM BO formats: `GBM_BO_FORMAT_{rgba-component-format}`
+
+    GBM specifies two 'BO formats', as aliases for the equivalent
+    `GBM_FORMAT_{rgba-component-format}` tokens. These format tokens are accepted
+    as input parameters to GBM buffer allocation entrypoints, however are never
+    returned as output from the API, e.g. via `gbm_bo_get_format`.
+
+    **`GBM_BO_FORMAT_ARGB8888`**
+
+    This is an alias for `GBM_FORMAT_ARGB8888`, and carries the same meaning.
+
+    **`GBM_BO_FORMAT_XRGB8888`**
+
+    This is an alias for `GBM_FORMAT_XRGB8888`, and carries the same meaning.
+
 * Multi-plane formats:
 
     We won't describe these in detail in this guide.

docs/index.md

@@ -50,7 +50,7 @@ help you understand the conventions used by the various pixel format families.
 * [BGRABitmap pixel formats](bgrabitmap.md)
 * [Cairo pixel formats](cairo.md)
 * [DirectFB pixel formats](directfb.md)
-* [DRM pixel formats](drm.md)
+* [DRM/GBM pixel formats](drm.md)
 * [OpenGL pixel formats](opengl.md)
 * [Pixman pixel formats](pixman.md)
 * [Qt pixel formats](qt.md)

docs/wayland_drm.md

@@ -1,5 +1,10 @@
 # Wayland-drm pixel formats
 
+This page describes the formats used by the private `wl_drm` extension,
+implemented by Mesa. This extension has been superseded by the linux-dmabuf
+extension, which provides a generic buffer-exchange protocol using the [DRM
+pixel format](drm.md) descriptors.
+
 The wayland-drm pixel formats follow the scheme:
 
     WL_DRM_FORMAT_{component-format}

pfg/drm.py

@@ -22,7 +22,7 @@
 from . import util
 import re
 
-drm_re = re.compile("DRM_FORMAT_(?P<components>.*)")
+drm_re = re.compile("(DRM|GBM)_FORMAT_(?P<components>.*)")
 
 drm_formats = [
     "DRM_FORMAT_C8",
@@ -84,6 +84,11 @@ def yuv_bits_to_memory(components):
     return util.split_bytes(components)
 
 def describe(format_str):
+    if format_str == "GBM_BO_FORMAT_XRGB8888":
+        format_str = "GBM_FORMAT_XRGB8888"
+    elif format_str == "GBM_BO_FORMAT_ARGB8888":
+        format_str = "GBM_FORMAT_ARGB8888"
+
     match = drm_re.match(format_str)
 
     if not match: