Linux needs a explicitly defined userspace API

Linux guarantees the stability of its userspace API, but the API itself is only informally described, primarily with English prose. We should write a explicit, authoritative definition of the Linux userspace API.

As background, note that the Linux userspace API (which consists of system calls, device files, various protocols, etc) is distinct from the C functions implemented by a libc, such as read(2). Under the hood, in a conventional libc like glibc, read(2) calls the Linux system call sys_read, manually passing arguments in registers in an architecture-specific way according to the specific details of sys_read. This is at best documented in manpages, and more usually is defined only by the implementation. Anyone else who wants to work with a sys_read syscall, in any way, needs to duplicate all those details.

If we created a explicit definition of the Linux userspace API, there would be numerous benefits:

A basic API definition would simply describe valid combinations and formats of syscall arguments in a machine-parseable form, something which is currently primarily described in English-language manpages. More detailed API definitions could describe behaviors such as the requirement that a syscall be passed an open file descriptor rather than an arbitrary integer, which would require a description of how different syscalls affect the file descriptor table.

To write this definition, a new Linux-specific format for the definition might need to be created. At a minimum, it will need to be able to describe bit-level data formats, complex pointer-based datastructures, tagged unions, "overloaded" syscalls such as ioctl, and architecture-specific divergences. Most existing formats and languages for describing interfaces like this unfortunately lack these capabilities.

Ultimately, this definition must be upstream, which means that it needs to be maintainable by existing Linux developers. One way to achieve that might be to integrate it into the C code, possibly in combination with existing Linux macros such as SYSCALL_DEFINE. The API description can then be automatically extracted from the C code into a more-easily-reusable format, which can be used as input for other tools.

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.

I would love to collaborate with anyone interested in creating an explicit, authoritative definition of the Linux API, so contact me if you're interested.