linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH] Documentation: gpu: Mention the requirements for new properties
@ 2021-05-11 15:55 Maxime Ripard
  2021-05-11 16:34 ` Alex Deucher
  2021-05-11 17:16 ` Daniel Vetter
  0 siblings, 2 replies; 3+ messages in thread
From: Maxime Ripard @ 2021-05-11 15:55 UTC (permalink / raw)
  To: dri-devel, Daniel Vetter, David Airlie, Maarten Lankhorst,
	Thomas Zimmermann, Maxime Ripard
  Cc: Maxime Ripard, Jonathan Corbet, linux-doc, linux-kernel

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.

Signed-off-by: Maxime Ripard <maxime@cerno.tech>
---
 Documentation/gpu/drm-kms.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index 87e5023e3f55..30f4c376f419 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -463,6 +463,24 @@ 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, with some documentation to describe the
+  property can be used.
+
+- 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
+  associated state structure.
+
+- An IGT test must be submitted.
+
 Property Types and Blob Property Support
 ----------------------------------------
 
-- 
2.31.1


^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH] Documentation: gpu: Mention the requirements for new properties
  2021-05-11 15:55 [PATCH] Documentation: gpu: Mention the requirements for new properties Maxime Ripard
@ 2021-05-11 16:34 ` Alex Deucher
  2021-05-11 17:16 ` Daniel Vetter
  1 sibling, 0 replies; 3+ messages in thread
From: Alex Deucher @ 2021-05-11 16:34 UTC (permalink / raw)
  To: Maxime Ripard
  Cc: Maling list - DRI developers, Daniel Vetter, David Airlie,
	Maarten Lankhorst, Thomas Zimmermann, Linux Doc Mailing List,
	LKML, Jonathan Corbet

On Tue, May 11, 2021 at 11:55 AM Maxime Ripard <maxime@cerno.tech> 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.
>
> Signed-off-by: Maxime Ripard <maxime@cerno.tech>
> ---
>  Documentation/gpu/drm-kms.rst | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 87e5023e3f55..30f4c376f419 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -463,6 +463,24 @@ 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, with some documentation to describe the

"to describe how the"

With that fixed, it looks good to me.

Alex

> +  property can be used.
> +
> +- 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
> +  associated state structure.
> +
> +- An IGT test must be submitted.
> +
>  Property Types and Blob Property Support
>  ----------------------------------------
>
> --
> 2.31.1
>

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH] Documentation: gpu: Mention the requirements for new properties
  2021-05-11 15:55 [PATCH] Documentation: gpu: Mention the requirements for new properties Maxime Ripard
  2021-05-11 16:34 ` Alex Deucher
@ 2021-05-11 17:16 ` Daniel Vetter
  1 sibling, 0 replies; 3+ messages in thread
From: Daniel Vetter @ 2021-05-11 17:16 UTC (permalink / raw)
  To: Maxime Ripard
  Cc: dri-devel, Daniel Vetter, David Airlie, Maarten Lankhorst,
	Thomas Zimmermann, linux-doc, linux-kernel, Jonathan Corbet

On Tue, May 11, 2021 at 05:55:12PM +0200, Maxime Ripard 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.
> 
> Signed-off-by: Maxime Ripard <maxime@cerno.tech>
> ---
>  Documentation/gpu/drm-kms.rst | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 87e5023e3f55..30f4c376f419 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -463,6 +463,24 @@ 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, with some documentation to describe the
> +  property can be used.
> +
> +- It must provide a generic helper in the core code to register that
> +  property on the object it attaches to.

Maybe also include anything that drivers might want to precompute, e.g. we
have helpers for cliprects.

> +
> +- Its content must be decoded by the core and provided in the object

								object's
> +  associated state structure.
> +
> +- An IGT test must be submitted.

				"... where reasonable."

We have that disclaimer already here:

https://dri.freedesktop.org/docs/drm/gpu/drm-uapi.html#testing-requirements-for-userspace-api

I think would be good to cross-reference the uapi rules in general

https://dri.freedesktop.org/docs/drm/gpu/drm-uapi.html#open-source-userspace-requirements

With the bikesheds addressed:

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

But this needs ideally a pile of acks from most display driver teams.
-Daniel

> +
>  Property Types and Blob Property Support
>  ----------------------------------------
>  
> -- 
> 2.31.1
> 

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

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2021-05-11 17:16 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-11 15:55 [PATCH] Documentation: gpu: Mention the requirements for new properties Maxime Ripard
2021-05-11 16:34 ` Alex Deucher
2021-05-11 17:16 ` Daniel Vetter

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).