UAPI doc (Re: KMS enums and bitfields UAPI)

[Pekka Paalanen]

On Wed, 15 Apr 2020 10:40:36 +0000
Simon Ser <contact at emersion.fr> wrote:

> On Tuesday, April 14, 2020 3:33 PM, Daniel Vetter <daniel at ffwll.ch> wrote:
> 
> > > What I'm suggesting isn't to make all enum values UAPI. I'm suggesting
> > > to add standard enum values as #defines in the UAPI headers to make
> > > these values UAPI. Non-standard properties wouldn't be in the UAPI
> > > headers, so user-space would need to query values from KMS just like
> > > they do now.  
> >
> > Hm that sounds like the half-way that wont work. Because then some
> > compositors will only use the hard-coded versions, and if they don't
> > have them, nag us to add them. And then be really disappointed if we
> > don't (or we screw up and add them where we shouldn't). That's the
> > status quo "let's have it both ways" that I think is the worst of all
> > options we have. So I guess from that pov the "userspace needs to
> > decode from symbolic values, always" as the only consistent one.  
> 
> Fair enough. Let's just continue using symbolic names then.

Hi,

I'm happy to see a decision made that is clear and simple, even if it
makes userspace need a little more code.

We as userspace programmers have a huge responsibility of figuring out
exactly how KMS UAPI is supposed to be used, and use it correctly,
because the UAPI is largely undocumented and whatever documentation
exists is not easily discoverable to a non-kernel developer.

Libdrm has a few man-pages that seem to have been left to rot. If I
could, bringing them up-to-date and extending to cover everything about
driver-agnostic KMS UAPI would seem like a nice idea. It would be the
obvious place for userspace oriented docs. After all, UAPI docs cannot
become incorrect over time (the stable UAPI promise), so the
maintenance effort would be just adding the new stuff and if necessary,
clarifying old stuff. No confusion with any kernel internal API that is
subject to change at any time.

https://www.kernel.org/doc/html/latest/ is really hard to find anything
in it when you need it. Often the terms you need to search for are not
the ones used in the UAPI or have far too many hits, assuming you know
what UAPI you would want to use in the first place.

Another disconnect is that libdrm API is not the UAPI exactly. So
documenting libdrm API with the kernel UAPI in mind would be the best.
People use libdrm more than kernel UAPI.


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/20200416/86957380/attachment.sig>