On Wed, 15 Apr 2020 10:40:36 +0000 Simon Ser wrote: > On Tuesday, April 14, 2020 3:33 PM, Daniel Vetter 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