Hi On Tue, Nov 18, 2014 at 3:43 PM, Thierry Reding <thierry.reding@xxxxxxxxx> 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@xxxxxxxxxx> >> > >> > 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@xxxxxxxxxx> >> >> 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 _______________________________________________ dri-devel mailing list dri-devel@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/dri-devel
