[Intel-gfx] [PATCH] i915, drm/fourcc: Improve the CCS modifier documentation

[Ben Widawsky]

On 17-08-18 11:34:40, Jason Ekstrand wrote:
>This updates the documentation on the intel CCS modifiers for a couple
>of reasons:
>
> 1) The old documentation required that the CCS modifier only be used
>    with 8888 formats.  While i915 currently only supports CCS scanout
>    with 8888 formats (and advertises such through the blob format), CCS
>    can be used with many other formats.  Mesa, in particular, can
>    handle CCS on the full range of formats supported by the hardware.
>    For image sharing entirely within userspace, we don't want this
>    restriction.
>
> 2) The old documentation specified the scaling factor in terms of
>    pixels which breaks down when you start using formats which are not
>    32-bit.  By specifying it in terms of cache lines and tiles, we can
>    properly specify the scale-down relationship with no format size
>    assumptions.
>
> 3) The new comment provides more detail about the "real" layout of CCS
>    on Sky Lake and also points out that the reason why Y tiling is
>    important is because it affects row pitch calculations.
>
> 4) We shouldn't be documenting the Yf CCS modifier yet.  Userspace is
>    incapable of generating it right now and we don't fully know how it
>    works yet.  Trying to fully describe it is premature.
>
>Signed-off-by: Jason Ekstrand <jason at jlekstrand.net>
>Cc: Ben Widawsky <ben at bwidawsk.net>
>Cc: Ville Syrjälä <ville.syrjala at linux.intel.com>
>---
> include/uapi/drm/drm_fourcc.h | 35 ++++++++++++++++++++++-------------
> 1 file changed, 22 insertions(+), 13 deletions(-)
>
>diff --git a/include/uapi/drm/drm_fourcc.h b/include/uapi/drm/drm_fourcc.h
>index 3ad838d..9670da4 100644
>--- a/include/uapi/drm/drm_fourcc.h
>+++ b/include/uapi/drm/drm_fourcc.h
>@@ -266,21 +266,30 @@ extern "C" {
> /*
>  * Intel color control surface (CCS) for render compression
>  *
>- * The framebuffer format must be one of the 8:8:8:8 RGB formats.
>- * The main surface will be plane index 0 and must be Y/Yf-tiled,
>- * the CCS will be plane index 1.
>- *
>- * Each CCS tile matches a 1024x512 pixel area of the main surface.
>- * To match certain aspects of the 3D hardware the CCS is
>- * considered to be made up of normal 128Bx32 Y tiles, Thus
>- * the CCS pitch must be specified in multiples of 128 bytes.
>- *
>- * In reality the CCS tile appears to be a 64Bx64 Y tile, composed
>- * of QWORD (8 bytes) chunks instead of OWORD (16 bytes) chunks.
>- * But that fact is not relevant unless the memory is accessed
>- * directly.
>+ * The image format must be compatible with CCS_E (lossless render
>+ * compression) as specified in the PRM for the relevant hardware.
>+ * The main surface will be plane index 0 and must be Y-tiled,
>+ * the CCS will be plane index 1 and is also Y-tiled.

I guess if you're future proofing, you might want to bake in the language for
planar formats.

>+ *
>+ * Each 64B cache line in the CCS (a region of 16B x 4 rows when
>+ * Y-tiled) corresponds to a region of 32x16 cache lines in the main
>+ * surface.  (As a corollary, each CCS tile corresponds to an area of
>+ * 32x16 tiles in the main surface.)  This relationship holds regardless
>+ * of the size of the number of bits per pixel of the image format.
>+ *
>+ * In reality, the cache lines in the CCS tile are proportioned in an
>+ * 8B x 8 row configuration with each byte being 2x2 2-bit CCS entries.
>+ * However, CCS is documented as Y-tiled with the scaling relationship
>+ * described in terms of cache lines as above so we consider it to be
>+ * Y-tiled for the purpose of specifying this modifier.  This means that
>+ * the row pitch for the CCS assumes 128B/tile.
>  */
> #define I915_FORMAT_MOD_Y_TILED_CCS	fourcc_mod_code(INTEL, 4)
>+
>+/* Reserved for the Yf version of the TILED_CCS modifier.
>+ *
>+ * Exact definition TBD.
>+ */
> #define I915_FORMAT_MOD_Yf_TILED_CCS	fourcc_mod_code(INTEL, 5)

Can we just rename this to RSVD, or does Mesa build already require this?

>
> /*