[PATCH v5] Documentation: gpu: Mention the requirements for new properties
Pekka Paalanen
ppaalanen at gmail.com
Fri Jul 9 07:24:44 UTC 2021
On Tue, 6 Jul 2021 18:12:44 +0200
Maxime Ripard <maxime at 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 at collabora.com>
Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20210709/91e8cd74/attachment.sig>
More information about the dri-devel
mailing list