Re: [PATCH v5] Documentation: gpu: Mention the requirements for new properties

[Pekka Paalanen <ppaalanen@gmail.com>]

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

On Tue,  6 Jul 2021 18:12:44 +0200
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.

...

> 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(+)
> 
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 87e5023e3f55..47994890fd1e 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -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;

Hi,

"variant" feels a little off to me, I would have used "value name
strings".

> +  * 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.

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.

> +
> +* An IGT test must be submitted where reasonable.
> +
>  Property Types and Blob Property Support
>  ----------------------------------------
>  

Regardless of my comments above:

Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>


Thanks,
pq

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]