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: Joel Stanley <[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: 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: 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 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 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 87e5023e3f55..bbe254dca635 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -463,6 +463,33 @@ 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.: + +- Before the introduction of any vendor-specific properties, they must + be first checked against the generic ones to avoid any conflict or + redundancy. + +- Vendor-specific properties must be prefixed by the vendor's name, + following the syntax "$vendor:$property". + +- Generic properties must be standardized, with some documentation to + describe how the property can be used. + +- Generic properties must provide a generic helper in the core code to + register that property on the object it attaches to. + +- Generic properties 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. + +- An IGT test should be submitted. + Property Types and Blob Property Support ---------------------------------------- -- 2.31.1
