Re: Documenting the kernel-user-space ABI

[Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 2570 bytes --]

On Tue 18 Mar 2014 16:00:21 Michael Kerrisk wrote:
> You raised a question at the bottom of a bug report
> (https://bugzilla.kernel.org/show_bug.cgi?id=70801#c4)
> that I though might better go to the list, since I
> think it merits some wider discussion:
> 
>     i'd like to have a master location to document all
>     this stuff at the kernel ABI level.  can we do that
>     with the man-pages project somehow without violating
>     the C library API tenet?
> 
> First though, I'd like to check: what do you mean by "all this stuff"?
> Am I correct to understand your question as something like:
> 
>     Can man-pages become a place where the kernel-user-space ABI
>     (as distinct from the glibc wrappers on top) is consistently
>     and thoroughly documented?

the linux-man-pages project is great at meeting the needs of the majority of 
developers -- those that live in userland with the C library between them and 
the kernel.

but i think there is not an insignificant number of developers who live at the 
direct kernel ABI level and do not want to see any C library details at all.  
like the people who write C libraries, or low level debugging utilities (i.e. 
anyone who touches ptrace -- gdb, qemu, strace just to name a few), or kernel 
developers themselves, or arch porters (who live in all the aforementioned 
sections), or test writers (like LTP), or researchers (academic, security, 
etc...), or the stubbornly curious.  i've worn most of these hats at some 
point in time and have been frustrated way more times than i can remember 
after trying to follow the man page for a function only to find out the kernel 
was slightly different.  doing `man foo` is a lot easier than going into the 
kernel and tracking down the actual function's source (and then tracing it 
through all the various subsystems to see how the diff args get treated).

basically i want this:
	http://thread.gmane.org/gmane.linux.kernel.cross-arch/21821
and i want documentation :).

the linux-man-pages project is already filling the critical documentation gap 
and rather than bootstrap another project, i was hoping we could find some way 
to integrate.  i understand the perfectly reasonable desire to not have to 
maintain multiple man pages that cover a lot of the same content (upwards of 
90%) when the functions are pretty one-to-one in flags/behavior (like the 
openat() syscall and the openat() C library function).  so maybe we need a 
technical solution to be able to split off the kernel-specific bits ?
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]