There have suggestions to bake pitch alignment, address alignement, contiguous memory or other placement (hidden VRAM, GTT/BAR, etc) constraints into modifiers. Last time this was brought up it seemed like the consensus was to not allow this. Document this in drm_fourcc.h.
There are several reasons for this.
- Encoding all of these constraints in the modifiers would explode the search space pretty quickly (we only have 64 bits to work with). - Modifiers need to be unambiguous: a buffer can only have a single modifier. - Modifier users aren't expected to parse modifiers (except drivers).
v2: add paragraph about aliases (Daniel)
v3: fix unrelated changes sent with the patch
v4: disambiguate users between driver and higher-level programs (Brian, Daniel)
v5: fix AFBC example (Brian, Daniel)
Signed-off-by: Simon Ser contact@emersion.fr Reviewed-by: Daniel Vetter daniel.vetter@ffwll.ch Cc: Daniel Stone daniel@fooishbar.org Cc: Bas Nieuwenhuizen bas@basnieuwenhuizen.nl Cc: Dave Airlie airlied@gmail.com Cc: Marek Olšák maraeo@gmail.com Cc: Alex Deucher alexdeucher@gmail.com Cc: Neil Armstrong narmstrong@baylibre.com Cc: Michel Dänzer michel@daenzer.net Cc: Brian Starkey brian.starkey@arm.com --- include/uapi/drm/drm_fourcc.h | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+)
diff --git a/include/uapi/drm/drm_fourcc.h b/include/uapi/drm/drm_fourcc.h index 490143500a50..8296197189bf 100644 --- a/include/uapi/drm/drm_fourcc.h +++ b/include/uapi/drm/drm_fourcc.h @@ -58,6 +58,34 @@ extern "C" { * may preserve meaning - such as number of planes - from the fourcc code, * whereas others may not. * + * Modifiers must uniquely encode buffer layout. In other words, a buffer must + * match only a single modifier. A modifier must not be a subset of layouts of + * another modifier. For instance, it's incorrect to encode pitch alignment in + * a modifier: a buffer may match a 64-pixel aligned modifier and a 32-pixel + * aligned modifier. That said, modifiers can have implicit minimal + * requirements. + * + * For modifiers where the combination of fourcc code and modifier can alias, + * a canonical pair needs to be defined and used by all drivers. An example + * is AFBC, where both ARGB and ABGR have the exact same compressed layout. + * + * For modifiers where the combination of fourcc code and modifier can alias, + * a canonical pair needs to be defined and used by all drivers. Preferred + * combinations are also encouraged where all combinations might lead to + * confusion and unnecessarily reduced interoperability. An example for the + * latter is AFBC, where the ABGR layouts are preferred over ARGB layouts. + * + * There are two kinds of modifier users: + * + * - Kernel and user-space drivers: for drivers it's important that modifiers + * don't alias, otherwise two drivers might support the same format but use + * different aliases, preventing them from sharing buffers in an efficient + * format. + * - Higher-level programs interfacing with KMS/GBM/EGL/Vulkan/etc: these users + * see modifiers as opaque tokens they can check for equality and intersect. + * These users musn't need to know to reason about the modifier value + * (i.e. they are not expected to extract information out of the modifier). + * * Vendors should document their modifier usage in as much detail as * possible, to ensure maximum compatibility across devices, drivers and * applications.