[RFC] drm: Start documenting userspace ABI

[David Herrmann]

Hi

On Tue, Nov 18, 2014 at 3:43 PM, Thierry Reding
<thierry.reding at gmail.com> wrote:
> On Tue, Nov 18, 2014 at 03:27:27PM +0100, Daniel Vetter wrote:
>> On Tue, Nov 18, 2014 at 03:19:33PM +0100, Thierry Reding wrote:
>> > From: Thierry Reding <treding at nvidia.com>
>> >
>> > After seeing how the DRM_IOCTL_MODE_CREATE_DUMB was implemented with
>> > different semantics on different drivers it seems like a good idea to
>> > start to more rigorously document userspace ABI to avoid these things
>> > in the future.
>> >
>> > This is a first draft of what such documentation could look like. Not
>> > all IOCTLs are documented and some explanation about the other system
>> > calls (mmap(), poll(), read(), ...) would be good too. But I wanted to
>> > send this out for early review to see if the direction is reasonable.
>> > If so my plan is to continue to chip away at this as I find time.
>> >
>> > Signed-off-by: Thierry Reding <treding at nvidia.com>
>>
>> Imo for ioctls the right thing to do is having proper manpages, not
>> kerneldoc or DocBook sections. manpages really lend themselves well to
>> specify all the different facets of a single interface.
>
> I don't think I've ever seen manpages document IOCTLs at this level of
> detail. The intention of this is to add documentation about the IOCTLs
> at the kernel/userspace transition. Keeping this in the kernel has the
> advantage that it's a whole lot easier to keep updated, much like what
> we do with the other kerneldoc.
>
> That doesn't mean we shouldn't have manpages, but I think both are for
> the most part orthogonal, even though they may describe various facets
> of the same interfaces.

tty_ioctl(4)
console_ioctl(4)

I think a similar man-page ala drm_ioctl(4) makes a lot of sense.

>> Also, we already have some skeleton of that in libdrm, so I think
>> extending that would be best.
>
> One other reason why I don't think libdrm is the best fit for this is
> that libdrm is just one userspace implementation abstracting away the
> interfaces that this describes. Not everyone will use libdrm. So in my
> opinion its great if libdrm documents the API that it exposes, but I
> don't think it should document the kernel interfaces that it uses. The
> kernel exposes them, so it should provide the documentation for it as
> well.

I don't mind documenting this in the kernel-doc. But if we start
something like drm_ioctl(4) (I pushed some more generic man-pages to
libdrm a few years ago), we have this documented in 2 places, which is
always annoying for updates.

And even if people don't use libdrm, I think it's totally acceptable
to ship man-pages with libdrm. Distributions are free to provide
drm-man-pages as stand-alone package (which is _really_ easy to
generate from libdrm).

Thanks
David