Documentation: gpu: Mention the requirements for new properties
Subsystems (3)
PATCH v5 1/1 Documentation: gpu: Mention the requirements for new properties
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.
---
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(+)
Documentation/gpu/drm-kms.rst +30 -0
@@ -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 ----------------------------------------
Signature · 1 line
2.31.1
Quoted 108 lines · Maxime Ripard
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 PekkaChanges from v3:
- Roll back to the v2
- Add Simon and Pekka in Cc
Quoted 7 lines
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 nameChanges from v1:
- Typos and wording reported by Daniel and Alex
Bunch of typos, but still lgtm.
Quoted 9 lines
--- Documentation/gpu/drm-kms.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)Documentation/gpu/drm-kms.rst +0
-0
Documentation/gpu/drm-kms.rst KMS Properties · line 470
Quoted 8 lines
Documentation/gpu/drm-kms.rst +5
-0@@ -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
s/need/needs/
Documentation/gpu/drm-kms.rst KMS Properties · line 476
Quoted 6 lines
Documentation/gpu/drm-kms.rst +6
-0+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;
I think that should be "variant's names" but not 100% sure.
Documentation/gpu/drm-kms.rst KMS Properties · line 486
Quoted 10 lines
Documentation/gpu/drm-kms.rst +10
-0+ * 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
Stuff auto-hyperlinks even in .rst files nowadays, so just sturct drm_clip_rect should be enough here. See
Documentation/gpu/drm-kms.rst KMS Properties · line 492
Quoted 6 lines
Documentation/gpu/drm-kms.rst +6
-0+ 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.
I like this addition.
Cheers, Daniel
Quoted 9 lines
Documentation/gpu/drm-kms.rst +3
-0+ +* An IGT test must be submitted where reasonable. + Property Types and Blob Property Support ----------------------------------------Signature · 1 line
2.31.1
Signature · 3 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
Quoted 6 lines · On Tue, 6 Jul 2021 18:12:44 +0200 Maxime Ripard <[email protected]> wrote:
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.
...
Quoted 27 lines
Changes from v4:
- Changes suggested by PekkaChanges from v3:
- Roll back to the v2
- Add Simon and Pekka in CcChanges 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 nameChanges from v1:
- Typos and wording reported by Daniel and Alex--- Documentation/gpu/drm-kms.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)Documentation/gpu/drm-kms.rst +1
-0@@ -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
Documentation/gpu/drm-kms.rst KMS Properties · line 476
Quoted 10 lines
Documentation/gpu/drm-kms.rst +10
-0+------------ + +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;
Hi,
"variant" feels a little off to me, I would have used "value name strings".
Quoted 6 lines
Documentation/gpu/drm-kms.rst +6
-0+ * 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.
Documentation/gpu/drm-kms.rst KMS Properties · line 492
Quoted 10 lines
Documentation/gpu/drm-kms.rst +10
-0+ +* 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.
I'd like to point out that this rule should apply also to properties that already exist in general, but are newly exposed in a driver for hardware that didn't expose the property before.
Documentation/gpu/drm-kms.rst KMS Properties · line 498
Quoted 6 lines
Documentation/gpu/drm-kms.rst +3
-0+ +* An IGT test must be submitted where reasonable. + Property Types and Blob Property Support ----------------------------------------
Regardless of my comments above:
Thanks,
pq
Quoted 67 lines · Pekka Paalanen
Quoted 6 lines · On Tue, 6 Jul 2021 18:12:44 +0200 Maxime Ripard <[email protected]> wrote:
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.
...
Quoted 27 lines
Changes from v4:
- Changes suggested by PekkaChanges from v3:
- Roll back to the v2
- Add Simon and Pekka in CcChanges 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 nameChanges from v1:
- Typos and wording reported by Daniel and Alex--- Documentation/gpu/drm-kms.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)Documentation/gpu/drm-kms.rst +1
-0@@ -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. +RequirementsDocumentation/gpu/drm-kms.rst KMS Properties · line 476
Quoted 10 lines
Documentation/gpu/drm-kms.rst +10
-0+------------ + +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;Hi,
"variant" feels a little off to me, I would have used "value name strings".
Quoted 12 lines
Documentation/gpu/drm-kms.rst +12
-0+ * 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. +
Quoted 8 lines
Documentation/gpu/drm-kms.rst KMS Properties · line 492
Quoted 4 lines
Documentation/gpu/drm-kms.rst +4
-0+* 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.I'd like to point out that this rule should apply also to properties that already exist in general, but are newly exposed in a driver for hardware that didn't expose the property before.
I think we should just make this a very strong recommendation, and in general encourage people to use the tests against their driver?
Otherwise a small "I'll just enable this" thing can become a huge project. And in general I think grandfathering existing things in is the pragmatic choice.
But maybe that could be a follow-up patch?
-Daniel
Quoted 15 lines
Documentation/gpu/drm-kms.rst KMS Properties · line 498
Quoted 7 lines
Documentation/gpu/drm-kms.rst +3
-0+ +* An IGT test must be submitted where reasonable. + Property Types and Blob Property Support ----------------------------------------Regardless of my comments above:
Reviewed-by Pekka Paalanen <[email protected]>Thanks,
pq
Signature · 3 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
Quoted 77 lines · On Fri, 9 Jul 2021 10:02:28 +0200 Daniel Vetter <[email protected]> wrote:
Quoted 67 lines · Pekka Paalanen
Quoted 6 lines · On Tue, 6 Jul 2021 18:12:44 +0200 Maxime Ripard <[email protected]> wrote:
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.
...
Quoted 27 lines
Changes from v4:
- Changes suggested by PekkaChanges from v3:
- Roll back to the v2
- Add Simon and Pekka in CcChanges 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 nameChanges from v1:
- Typos and wording reported by Daniel and Alex--- Documentation/gpu/drm-kms.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)Documentation/gpu/drm-kms.rst +1
-0@@ -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. +RequirementsDocumentation/gpu/drm-kms.rst KMS Properties · line 476
Quoted 10 lines
Documentation/gpu/drm-kms.rst +10
-0+------------ + +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;Hi,
"variant" feels a little off to me, I would have used "value name strings".
Quoted 12 lines
Documentation/gpu/drm-kms.rst +12
-0+ * 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. +Quoted 8 lines
Documentation/gpu/drm-kms.rst KMS Properties · line 492
Quoted 4 lines
Documentation/gpu/drm-kms.rst +4
-0+* 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.I'd like to point out that this rule should apply also to properties that already exist in general, but are newly exposed in a driver for hardware that didn't expose the property before.
Quoted 8 lines
I think we should just make this a very strong recommendation, and in general encourage people to use the tests against their driver?
Otherwise a small "I'll just enable this" thing can become a huge project. And in general I think grandfathering existing things in is the pragmatic choice.
But maybe that could be a follow-up patch?
Sure, I don't mind. Just saying now that it came to mind. Drivers do not arbitrarily change behaviour without exposing more properties either, right?
Thanks,
pq
Quoted 20 lines
-Daniel
Quoted 15 lines
Documentation/gpu/drm-kms.rst KMS Properties · line 498
Quoted 7 lines
Documentation/gpu/drm-kms.rst +3
-0+ +* An IGT test must be submitted where reasonable. + Property Types and Blob Property Support ----------------------------------------Regardless of my comments above:
Reviewed-by Pekka Paalanen <[email protected]>Thanks,
pq
Quoted 87 lines · Pekka Paalanen
Quoted 84 lines · On Fri, 9 Jul 2021 10:02:28 +0200 Daniel Vetter <[email protected]> wrote:
Quoted 67 lines · Pekka Paalanen
Quoted 6 lines · On Tue, 6 Jul 2021 18:12:44 +0200 Maxime Ripard <[email protected]> wrote:
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.
...
Quoted 27 lines
Changes from v4:
- Changes suggested by PekkaChanges from v3:
- Roll back to the v2
- Add Simon and Pekka in CcChanges 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 nameChanges from v1:
- Typos and wording reported by Daniel and Alex--- Documentation/gpu/drm-kms.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)Documentation/gpu/drm-kms.rst +1
-0@@ -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. +RequirementsDocumentation/gpu/drm-kms.rst KMS Properties · line 476
Quoted 10 lines
Documentation/gpu/drm-kms.rst +10
-0+------------ + +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;Hi,
"variant" feels a little off to me, I would have used "value name strings".
Quoted 12 lines
Documentation/gpu/drm-kms.rst +12
-0+ * 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. +Quoted 8 lines
Documentation/gpu/drm-kms.rst KMS Properties · line 492
Quoted 4 lines
Documentation/gpu/drm-kms.rst +4
-0+* 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.I'd like to point out that this rule should apply also to properties that already exist in general, but are newly exposed in a driver for hardware that didn't expose the property before.
I think we should just make this a very strong recommendation, and in general encourage people to use the tests against their driver?
Otherwise a small "I'll just enable this" thing can become a huge project. And in general I think grandfathering existing things in is the pragmatic choice.
Quoted 5 lines
Quoted 1 line
But maybe that could be a follow-up patch?
Sure, I don't mind. Just saying now that it came to mind. Drivers do not arbitrarily change behaviour without exposing more properties either, right?
Yup. Both are covered under the "no regressions" rule, but better to make this explicit. Maybe we should replicate some of the key bits in the property docs for drivers?
Also anytime we spot an issue we need to improve the internal helpers to make sure things stay consistent.
-Daniel
Quoted 27 lines
Thanks,
pqQuoted 20 lines
-Daniel
Quoted 15 lines
Documentation/gpu/drm-kms.rst KMS Properties · line 498
Quoted 7 lines
Documentation/gpu/drm-kms.rst +3
-0+ +* An IGT test must be submitted where reasonable. + Property Types and Blob Property Support ----------------------------------------Regardless of my comments above:
Reviewed-by Pekka Paalanen <[email protected]>Thanks,
pq
Signature · 3 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch