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

[Daniel Vetter]

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