[RFC] drm: Start documenting userspace ABI

[Laurent Pinchart]

On Wednesday 19 November 2014 14:23:47 Daniel Vetter wrote:
> On Tue, Nov 18, 2014 at 04:24:39PM +0100, Thierry Reding wrote:
> > On Tue, Nov 18, 2014 at 04:05:08PM +0100, David Herrmann wrote:
> > > On Tue, Nov 18, 2014 at 3:43 PM, Thierry Reding 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.

The DRM API is much more complex, I think it deserves one page per ioctl.

> > > >> 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.
> > 
> > I wonder if it would somehow be possible to generate manpages from the
> > DocBook to avoid this duplication.

I'm pretty sure that should be possible. DocBook has appropriate markup to 
document functions in a manpage-like manner, see 
http://linuxtv.org/downloads/v4l-dvb-apis/vidioc-reqbufs.html for instance.

> > One of the things that DRM_IOCTL_MODE_CREATE_DUMB showed is that both
> > drivers and userspace can interpret things wrongly, and I fear that if all
> > we have is a manpage to document the IOCTLs, people writing the drivers
> > may not be tempted enough to read that manpage. So I think we want
> > documentation for both driver and userspace developers.
> 
> Imo docs don't help with that kind of fumble, only nasty testcases will.
> People only read docs when they don't understand stuff (i.e. trying to
> write drivers). Imo manpages an ioctl docs are only really good for
> designing the interface (since it forces you to really think through the
> semantics to be able to describe them concisely and precisely). But even
> there I think having solid testcases is better invested time.
> 
> Documentation for developers is imo an entirely different matter, I think
> that gets used a lot more. Or at least I find them fairly useful.

I think both are useful. From my personal experience proper detailed ioctl 
documentation helps a lots when writing kernel drivers. Even in the case of 
the DRM subsystem where various helper functions push the driver away from the 
ioctl API, proper documentation of the structures passed by userspace is very 
helpful for driver developers.  Not to mention of course that the 
documentation helps getting the helpers right.

Test cases are also invaluable. I've seen both test cases being used to fix 
drivers and documentation, clarifying the API as they get developed. 
Implementing a test case is a very good way to test the maturity of an API.

> > Documenting this within the kernel is also pretty easy. I know that I'll
> > be much more tempted to do it within the kernel than if I have to switch
> > to some other repository, build system and whatnot.

I agree. Having code and documentation close to each other will benefit both.

> > Perhaps in this case having two places where it's documented isn't all
> > that bad. It's ABI after all, so the documentation never needs to
> > change. Theoretically.
> > 
> > > 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).
> > 
> > I guess one other home for these could be the man-pages project on
> > kernel.org. It's what carries most (all?) of the Linux kernel-specific
> > man-pages (like the tty_ioctl and console_ioctl ones that you referred
> > to).
> 
> There has been talks about merging the linux manpages back into the kernel
> actually. But yeah that seems like a good home, especially since Micheal
> Kerrisk seems pretty sharp with reviewing manpages.

-- 
Regards,

Laurent Pinchart