New KMS properties come with a bunch of requirements to avoid each driver from running their own, inconsistent, set of properties, eventually leading to issues like property conflicts, inconsistencies between drivers and semantics, etc.
Let's document what we expect. Cc: Alexandre Belloni <[email protected]> Cc: Alexandre Torgue <[email protected]> Cc: Alex Deucher <[email protected]> Cc: Alison Wang <[email protected]> Cc: Alyssa Rosenzweig <[email protected]> Cc: Andrew Jeffery <[email protected]> Cc: Andrzej Hajda <[email protected]> Cc: Anitha Chrisanthus <[email protected]> Cc: Benjamin Gaignard <[email protected]> Cc: Ben Skeggs <[email protected]> Cc: Boris Brezillon <[email protected]> Cc: Brian Starkey <[email protected]> Cc: Chen Feng <[email protected]> Cc: Chen-Yu Tsai <[email protected]> Cc: Christian Gmeiner <[email protected]> Cc: "Christian König" <[email protected]> Cc: Chun-Kuang Hu <[email protected]> Cc: Edmund Dea <[email protected]> Cc: Eric Anholt <[email protected]> Cc: Fabio Estevam <[email protected]> Cc: Gerd Hoffmann <[email protected]> Cc: Haneen Mohammed <[email protected]> Cc: Hans de Goede <[email protected]> Cc: "Heiko Stübner" <[email protected]> Cc: Huang Rui <[email protected]> Cc: Hyun Kwon <[email protected]> Cc: Inki Dae <[email protected]> Cc: Jani Nikula <[email protected]> Cc: Jernej Skrabec <[email protected]> Cc: Jerome Brunet <[email protected]> Cc: John Stultz <[email protected]> Cc: Jonas Karlman <[email protected]> Cc: Jonathan Hunter <[email protected]> Cc: Joonas Lahtinen <[email protected]> Cc: Joonyoung Shim <[email protected]> Cc: Jyri Sarha <[email protected]> Cc: Kevin Hilman <[email protected]> Cc: Kieran Bingham <[email protected]> Cc: Krzysztof Kozlowski <[email protected]> Cc: Kyungmin Park <[email protected]> Cc: Laurent Pinchart <[email protected]> Cc: Linus Walleij <[email protected]> Cc: Liviu Dudau <[email protected]> Cc: Lucas Stach <[email protected]> Cc: Ludovic Desroches <[email protected]> Cc: Marek Vasut <[email protected]> Cc: Martin Blumenstingl <[email protected]> Cc: Matthias Brugger <[email protected]> Cc: Maxime Coquelin <[email protected]> Cc: Maxime Ripard <[email protected]> Cc: Melissa Wen <[email protected]> Cc: Neil Armstrong <[email protected]> Cc: Nicolas Ferre <[email protected]> Cc: "Noralf Trønnes" <[email protected]> Cc: NXP Linux Team <[email protected]> Cc: Oleksandr Andrushchenko <[email protected]> Cc: Patrik Jakobsson <[email protected]> Cc: Paul Cercueil <[email protected]> Cc: Pekka Paalanen <[email protected]> Cc: Pengutronix Kernel Team <[email protected]> Cc: Philippe Cornu <[email protected]> Cc: Philipp Zabel <[email protected]> Cc: Qiang Yu <[email protected]> Cc: Rob Clark <[email protected]> Cc: Robert Foss <[email protected]> Cc: Rob Herring <[email protected]> Cc: Rodrigo Siqueira <[email protected]> Cc: Rodrigo Vivi <[email protected]> Cc: Roland Scheidegger <[email protected]> Cc: Russell King <[email protected]> Cc: Sam Ravnborg <[email protected]> Cc: Sandy Huang <[email protected]> Cc: Sascha Hauer <[email protected]> Cc: Sean Paul <[email protected]> Cc: Seung-Woo Kim <[email protected]> Cc: Shawn Guo <[email protected]> Cc: Simon Ser <[email protected]> Cc: Stefan Agner <[email protected]> Cc: Steven Price <[email protected]> Cc: Sumit Semwal <[email protected]> Cc: Thierry Reding <[email protected]> Cc: Tian Tao <[email protected]> Cc: Tomeu Vizoso <[email protected]> Cc: Tomi Valkeinen <[email protected]> Cc: VMware Graphics <[email protected]> Cc: Xinliang Liu <[email protected]> Cc: Xinwei Kong <[email protected]> Cc: Yannick Fertre <[email protected]> Cc: Zack Rusin <[email protected]> Reviewed-by: Daniel Vetter <[email protected]> Signed-off-by: Maxime Ripard <[email protected]> --- Changes from v4: - Changes suggested by Pekka Changes from v3: - Roll back to the v2 - Add Simon and Pekka in Cc Changes from v2: - Take into account the feedback from Laurent and Lidiu to no longer force generic properties, but prefix vendor-specific properties with the vendor name Changes from v1: - Typos and wording reported by Daniel and Alex --- Documentation/gpu/drm-kms.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 87e5023e3f55..47994890fd1e 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -463,6 +463,36 @@ KMS Properties This section of the documentation is primarily aimed at user-space developers. For the driver APIs, see the other sections. +Requirements +------------ + +KMS drivers might need to add extra properties to support new features. +Each new property introduced in a driver need to meet a few +requirements, in addition to the one mentioned above: + +* It must be standardized, documenting: + + * The full, exact, name string; + * If the property is an enum, all the valid variants name; + * What values are accepted, and what these values mean; + * What the property does and how it can be used; + * How the property might interact with other, existing properties. + +* It must provide a generic helper in the core code to register that + property on the object it attaches to. + +* Its content must be decoded by the core and provided in the object's + associated state structure. That includes anything drivers might want + to precompute, like :c:type:`struct drm_clip_rect <drm_clip_rect>` for + planes. + +* Its initial state must match the behavior prior to the property + introduction. This might be a fixed value matching what the hardware + does, or it may be inherited from the state the firmware left the + system in during boot. + +* An IGT test must be submitted where reasonable. + Property Types and Blob Property Support ---------------------------------------- -- 2.31.1
