Skip to contentSkip to conversation

Documentation: gpu: Mention the requirements for new properties

PATCH Superseded Maxime Ripard 3 participants 6 messages Jul 6, 2021 – Jul 12, 2021

Subsystems (3)

v5 of 6 Superseded Latest is v6 →

lore
Share & tools
lore
#0 lore raw

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.

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]>

---

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
index 87e5023e3f55..47994890fd1e 100644
@@ -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
#1 lore raw
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]>

---

Changes from v4:
- Changes suggested by Pekka

Changes 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 name

Changes 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
index 87e5023e3f55..47994890fd1e 100644

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

https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#cross-referencing-from-restructuredtext

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
Reviewed-by on v5 1/1
#2 lore raw
In reply to Maxime Ripard
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 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 +1 -0
index 87e5023e3f55..47994890fd1e 100644
@@ -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

#3 lore raw
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 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 +1 -0
index 87e5023e3f55..47994890fd1e 100644
@@ -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 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:

Thanks,
pq

Signature · 3 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
#4 lore raw
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 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 +1 -0
index 87e5023e3f55..47994890fd1e 100644
@@ -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 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:

Thanks,
pq

#5 lore raw
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 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 +1 -0
index 87e5023e3f55..47994890fd1e 100644
@@ -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 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,
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:

Thanks,
pq

Signature · 3 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch