[PATCH] drm: add modifiers for Apple twiddled layouts

[PATCH] drm: add modifiers for Apple twiddled layouts

[Alyssa Rosenzweig]

Apple supports a few image layouts across the SoC. To begin, add
modifiers for the "twiddled" and "twiddled + compressed" layouts. These
are the two "standard" layouts used on the GPU. Mesa requires these
modifiers to share non-linear buffers across processes, but no other
userspace or kernel support is required/expected.

These layouts are notably not used for interchange across hardware
blocks (e.g. with the display controller). There are other layouts for
those but we don't support them either in userspace or kernelspace yet
(even downstream), so we're not adding them here.

Signed-off-by: Alyssa Rosenzweig <alyssa@rosenzweig.io>
---
 include/uapi/drm/drm_fourcc.h | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/include/uapi/drm/drm_fourcc.h b/include/uapi/drm/drm_fourcc.h
index e41a3cec6a9ed18760f3b0c88ba437c9aba3dd4f..6c289fc172c099ab32bf539a1698dabb93f9a0d2 100644
--- a/include/uapi/drm/drm_fourcc.h
+++ b/include/uapi/drm/drm_fourcc.h
@@ -422,6 +422,7 @@ extern "C" {
 #define DRM_FORMAT_MOD_VENDOR_ALLWINNER 0x09
 #define DRM_FORMAT_MOD_VENDOR_AMLOGIC 0x0a
 #define DRM_FORMAT_MOD_VENDOR_MTK     0x0b
+#define DRM_FORMAT_MOD_VENDOR_APPLE   0x0c
 
 /* add more to the end as needed */
 
@@ -1494,6 +1495,36 @@ drm_fourcc_canonicalize_nvidia_format_mod(__u64 modifier)
 /* alias for the most common tiling format */
 #define DRM_FORMAT_MOD_MTK_16L_32S_TILE  DRM_FORMAT_MOD_MTK(MTK_FMT_MOD_TILE_16L32S)
 
+/*
+ * Apple twiddled layout.
+ *
+ * This is the most "general" image layout supported on Apple GPUs.
+ *
+ * Twiddled images are divided into tiles. Tiles are always 16KiB, with
+ * dimensions depending on the base-format. Within a tile, pixels are fully
+ * interleaved (Morton order). Tiles themselves are raster-order.
+ *
+ * Images must be 16-byte aligned.
+ *
+ * For more information see
+ * https://docs.mesa3d.org/drivers/asahi.html#image-layouts
+ */
+#define DRM_FORMAT_MOD_APPLE_TWIDDLED fourcc_mod_code(APPLE, 1)
+
+/*
+ * Apple twiddled and compressed layout.
+ *
+ * This is the main lossless image compression layout supported by Apple GPUs.
+ *
+ * The image is divided into tiles that are internally twiddled.  In addition to
+ * the body, there is also a metadata section containing 8 bytes for each 16x16
+ * compression subtile. By convention, the metadata immediately follows the
+ * body, after padding to 128-bytes.
+ *
+ * Images must be 16-byte aligned.
+ */
+#define DRM_FORMAT_MOD_APPLE_TWIDDLED_COMPRESSED fourcc_mod_code(APPLE, 2)
+
 /*
  * AMD modifiers
  *

---
base-commit: 0ed1356af8f629ae807963b7db4e501e3b580bc2
change-id: 20250218-apple-twiddled-modifiers-fde1a6f4300c

Best regards,
-- 
Alyssa Rosenzweig <alyssa@rosenzweig.io>

Re: [PATCH] drm: add modifiers for Apple twiddled layouts

[Janne Grunau]

Hej,

On Tue, Feb 18, 2025 at 11:15:54AM -0500, Alyssa Rosenzweig wrote:
> Apple supports a few image layouts across the SoC. To begin, add
> modifiers for the "twiddled" and "twiddled + compressed" layouts. These
> are the two "standard" layouts used on the GPU. Mesa requires these
> modifiers to share non-linear buffers across processes, but no other
> userspace or kernel support is required/expected.
> 
> These layouts are notably not used for interchange across hardware
> blocks (e.g. with the display controller). There are other layouts for
> those but we don't support them either in userspace or kernelspace yet
> (even downstream), so we're not adding them here.
> 
> Signed-off-by: Alyssa Rosenzweig <alyssa@rosenzweig.io>
> ---
>  include/uapi/drm/drm_fourcc.h | 31 +++++++++++++++++++++++++++++++
>  1 file changed, 31 insertions(+)
> 
> diff --git a/include/uapi/drm/drm_fourcc.h b/include/uapi/drm/drm_fourcc.h
> index e41a3cec6a9ed18760f3b0c88ba437c9aba3dd4f..6c289fc172c099ab32bf539a1698dabb93f9a0d2 100644
> --- a/include/uapi/drm/drm_fourcc.h
> +++ b/include/uapi/drm/drm_fourcc.h
> @@ -422,6 +422,7 @@ extern "C" {
>  #define DRM_FORMAT_MOD_VENDOR_ALLWINNER 0x09
>  #define DRM_FORMAT_MOD_VENDOR_AMLOGIC 0x0a
>  #define DRM_FORMAT_MOD_VENDOR_MTK     0x0b
> +#define DRM_FORMAT_MOD_VENDOR_APPLE   0x0c
>  
>  /* add more to the end as needed */
>  
> @@ -1494,6 +1495,36 @@ drm_fourcc_canonicalize_nvidia_format_mod(__u64 modifier)
>  /* alias for the most common tiling format */
>  #define DRM_FORMAT_MOD_MTK_16L_32S_TILE  DRM_FORMAT_MOD_MTK(MTK_FMT_MOD_TILE_16L32S)
>  
> +/*
> + * Apple twiddled layout.
> + *
> + * This is the most "general" image layout supported on Apple GPUs.
> + *
> + * Twiddled images are divided into tiles. Tiles are always 16KiB, with
> + * dimensions depending on the base-format. Within a tile, pixels are fully
> + * interleaved (Morton order). Tiles themselves are raster-order.
> + *
> + * Images must be 16-byte aligned.
> + *
> + * For more information see
> + * https://docs.mesa3d.org/drivers/asahi.html#image-layouts
> + */
> +#define DRM_FORMAT_MOD_APPLE_TWIDDLED fourcc_mod_code(APPLE, 1)
> +
> +/*
> + * Apple twiddled and compressed layout.
> + *
> + * This is the main lossless image compression layout supported by Apple GPUs.
> + *
> + * The image is divided into tiles that are internally twiddled.  In addition to

Does the compressed format uses the same the sime tile sizes (in pixel
dimensions) and layout as DRM_FORMAT_MOD_APPLE_TWIDDLED? I'd assume so
but I think it's worth stating explictly.

> + * the body, there is also a metadata section containing 8 bytes for each 16x16
> + * compression subtile. By convention, the metadata immediately follows the
> + * body, after padding to 128-bytes.
> + *
> + * Images must be 16-byte aligned.
> + */
> +#define DRM_FORMAT_MOD_APPLE_TWIDDLED_COMPRESSED fourcc_mod_code(APPLE, 2)
> +

ciao Janne

Re: [PATCH] drm: add modifiers for Apple twiddled layouts

[Alyssa Rosenzweig]

> > +/*
> > + * Apple twiddled and compressed layout.
> > + *
> > + * This is the main lossless image compression layout supported by Apple GPUs.
> > + *
> > + * The image is divided into tiles that are internally twiddled.  In addition to
> 
> Does the compressed format uses the same the sime tile sizes (in pixel
> dimensions) and layout as DRM_FORMAT_MOD_APPLE_TWIDDLED? I'd assume so
> but I think it's worth stating explictly.

It does. I'll reword to make that more clear.