Hi
On Tue, Nov 18, 2014 at 3:43 PM, Thierry Reding thierry.reding@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@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@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