[PATCH v2] drm: Document requirements for driver-specific KMS props in new drivers

[PATCH v2] drm: Document requirements for driver-specific KMS props in new drivers

[Sebastian Wick]

When extending support for a driver-specific KMS property to additional
drivers, we should apply all the requirements for new properties and
make sure the semantics are the same and documented.

v2: devs of the driver which introduced property shall help and ack

Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
---
 Documentation/gpu/drm-kms.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index 13d3627d8bc0..b98b98359c90 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -496,6 +496,13 @@ addition to the one mentioned above:
 
 * An IGT test must be submitted where reasonable.
 
+For historical reasons, non-standard, driver-specific properties exist. If a KMS
+driver wants to add support for one of those properties, the requirements for
+new properties apply where possible. Additionally, the documented behavior must
+match the de facto semantics of the existing property to ensure compatibility.
+Developers of the driver that first added the property should help with those
+tasks and must ACK the documented behavior if possible.
+
 Property Types and Blob Property Support
 ----------------------------------------
 
-- 
2.44.0

Re: [PATCH v2] drm: Document requirements for driver-specific KMS props in new drivers

[Maxime Ripard]

[-- Attachment #1: Type: text/plain, Size: 527 bytes --]

On Mon, Mar 11, 2024 at 04:58:58PM +0100, Sebastian Wick wrote:
> When extending support for a driver-specific KMS property to additional
> drivers, we should apply all the requirements for new properties and
> make sure the semantics are the same and documented.
> 
> v2: devs of the driver which introduced property shall help and ack
> 
> Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>

Acked-by: Maxime Ripard <mripard@kernel.org>

We probably want to have Dave or Sima ack on that one too

Maxime

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2] drm: Document requirements for driver-specific KMS props in new drivers

[Daniel Vetter]

On Thu, Mar 14, 2024 at 11:20:09AM +0100, Maxime Ripard wrote:
> On Mon, Mar 11, 2024 at 04:58:58PM +0100, Sebastian Wick wrote:
> > When extending support for a driver-specific KMS property to additional
> > drivers, we should apply all the requirements for new properties and
> > make sure the semantics are the same and documented.
> > 
> > v2: devs of the driver which introduced property shall help and ack
> > 
> > Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
> 
> Acked-by: Maxime Ripard <mripard@kernel.org>
> 
> We probably want to have Dave or Sima ack on that one too

Yeah that's a good idea and defacto how we handled this - additional users
of anything (whether library or uapi or whatever) get to clean up an
existing mess if it's too bad. But for uapi it's good to be really
explicit and document that.

Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>

Cheers, Sima
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

[PATCH v2] drm: Document requirements for driver-specific KMS props in new drivers

[Sebastian Wick]

When extending support for a driver-specific KMS property to additional
drivers, we should apply all the requirements for new properties and
make sure the semantics are the same and documented.

v2: devs of the driver which introduced property shall help and ack

Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
Acked-by: Maxime Ripard <mripard@kernel.org>
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 Documentation/gpu/drm-kms.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index 13d3627d8bc0..b98b98359c90 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -496,6 +496,13 @@ addition to the one mentioned above:
 
 * An IGT test must be submitted where reasonable.
 
+For historical reasons, non-standard, driver-specific properties exist. If a KMS
+driver wants to add support for one of those properties, the requirements for
+new properties apply where possible. Additionally, the documented behavior must
+match the de facto semantics of the existing property to ensure compatibility.
+Developers of the driver that first added the property should help with those
+tasks and must ACK the documented behavior if possible.
+
 Property Types and Blob Property Support
 ----------------------------------------
 
-- 
2.44.0