drm/fourcc: document modifier uniqueness requirements

There have suggestions to bake pitch alignment, address alignment, 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) v6: remove duplicated paragraph (Daniel)

Simon Ser committed 6 years ago

Commit ec5722a1 parent 178c7231 file · +24 −0Browse files

Showing the changes to include/uapi (1 of 1 file). Show all

Unified · Split

include/uapi/drm/drm_fourcc.h+24−0

@@ -58,6 +58,30 @@ extern "C" { · 57 unmodified lines
58	58	* may preserve meaning - such as number of planes - from the fourcc code,
59	59	* whereas others may not.
60	60	*
	61	+ * Modifiers must uniquely encode buffer layout. In other words, a buffer must
	62	+ * match only a single modifier. A modifier must not be a subset of layouts of
	63	+ * another modifier. For instance, it's incorrect to encode pitch alignment in
	64	+ * a modifier: a buffer may match a 64-pixel aligned modifier and a 32-pixel
	65	+ * aligned modifier. That said, modifiers can have implicit minimal
	66	+ * requirements.
	67	+ *
	68	+ * For modifiers where the combination of fourcc code and modifier can alias,
	69	+ * a canonical pair needs to be defined and used by all drivers. Preferred
	70	+ * combinations are also encouraged where all combinations might lead to
	71	+ * confusion and unnecessarily reduced interoperability. An example for the
	72	+ * latter is AFBC, where the ABGR layouts are preferred over ARGB layouts.
	73	+ *
	74	+ * There are two kinds of modifier users:
	75	+ *
	76	+ * - Kernel and user-space drivers: for drivers it's important that modifiers
	77	+ * don't alias, otherwise two drivers might support the same format but use
	78	+ * different aliases, preventing them from sharing buffers in an efficient
	79	+ * format.
	80	+ * - Higher-level programs interfacing with KMS/GBM/EGL/Vulkan/etc: these users
	81	+ * see modifiers as opaque tokens they can check for equality and intersect.
	82	+ * These users musn't need to know to reason about the modifier value
	83	+ * (i.e. they are not expected to extract information out of the modifier).
	84	+ *
61	85	* Vendors should document their modifier usage in as much detail as
62	86	* possible, to ensure maximum compatibility across devices, drivers and
63	87	* applications.