UAPI doc (Re: KMS enums and bitfields UAPI)

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Wed, 15 Apr 2020 10:40:36 +0000
Simon Ser <contact@xxxxxxxxxxx> wrote:

> On Tuesday, April 14, 2020 3:33 PM, Daniel Vetter <daniel@xxxxxxxx> 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

Attachment: pgpnmJTAnmdVy.pgp
Description: OpenPGP digital signature

_______________________________________________
dri-devel mailing list
dri-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[Index of Archives]     [Linux DRI Users]     [Linux Intel Graphics]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]
  Powered by Linux