[PATCH v5] Documentation: gpu: Mention the requirements for new properties
Daniel Vetter
daniel at ffwll.ch
Fri Jul 9 08:02:28 UTC 2021
On Fri, Jul 09, 2021 at 10:24:44AM +0300, Pekka Paalanen wrote:
> 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.
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
>
> > +
> > +* 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
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
More information about the dri-devel
mailing list