On Wed, Apr 20, 2022 at 04:15:25PM +0000, Spencer Baugh wrote: > > Linux guarantees the stability of its userspace API, but the API > itself is only informally described, primarily with English prose. I > want to add an explicit, authoritative machine-readable definition of > the Linux userspace API. > > As background, in a conventional libc like glibc, read(2) calls the > Linux system call read, passing arguments in an architecture-specific > way according to the specific details of read. > > The details of these syscalls are at best documented in manpages, and > often defined only by the implementation. Anyone else who wants to > work with a syscall, in any way, needs to duplicate all those details. > > So the most basic definition of the API would just represent the > information already present in SYSCALL_DEFINE macros: the C types of > arguments and return values. More usefully, it would describe the > formats of those arguments and return values: that the first argument > to read is a file descriptor rather than an arbitrary integer, and > what flags are valid in the flags argument of openat, and that open > returns a file descriptor. A step beyond that would be describing, in > some limited way, the effects of syscalls; for example, that read > writes into the passed buffer the number of bytes that it returned. So how would you define read() in this format in a way that has not already been attempted in the past? How are you going to define a format that explains functionality in a way that is not just the implementation in the end? > One step in this direction is Documentation/ABI, which specifies the > stability guarantees for different userspace APIs in a semi-formal > way. But it doesn't specify the actual content of those APIs, and it > doesn't cover individual syscalls at all. The content is described in Documentation/ABI/ entries, where do you see that missing? And you are correct, that place does not describe syscalls, or other user/kernel interfaces that predate sysfs. good luck! greg k-h
