[RFC 00/19] Kernel API Specification Framework

Sasha Levin
2025-06-14T13:49:00Z

This patch series introduces a framework for formally specifying kernel
APIs, addressing the long-standing challenge of maintaining stable
interfaces between the kernel and user-space programs. As outlined in
previous discussions about kernel ABI stability, the lack of
machine-readable API specifications has led to inadvertent breakages and
inconsistent validation across system calls and IOCTLs.

The framework provides three key components: declarative macros for
specifying system call and IOCTL interfaces directly in the kernel
source, automated extraction tools for generating machine-readable
specifications, and a runtime validation infrastructure accessible
through debugfs. By embedding specifications alongside implementation
code, we ensure they remain synchronized and enable automated detection
of API/ABI changes that could break user-space applications.

This implementation demonstrates the approach with specifications for
core system calls (epoll, exec, mlock families) and complex IOCTL
interfaces (binder, fwctl). The specifications capture parameter types,
validation rules, return values, and error conditions in a structured
format that enables both documentation generation and runtime
verification. Future work will expand coverage to additional subsystems
and integrate with existing testing infrastructure to provide
API compatibility guarantees.

To complement the framework, we introduce the 'kapi' tool - a
utility for extracting and analyzing kernel API specifications from
multiple sources. The tool can extract specifications from kernel source
code (parsing KAPI macros), compiled vmlinux binaries (reading the
.kapi_specs ELF section), or from a running kernel via debugfs. It
supports multiple output formats (plain text, JSON, RST) to facilitate
integration with documentation systems and automated testing workflows.
This tool enables developers to easily inspect API specifications,
verify changes across kernel versions, and generate documentation
without requiring kernel rebuilds.

Sasha Levin (19):
kernel/api: introduce kernel API specification framework
eventpoll: add API specification for epoll_create1
eventpoll: add API specification for epoll_create
eventpoll: add API specification for epoll_ctl
eventpoll: add API specification for epoll_wait
eventpoll: add API specification for epoll_pwait
eventpoll: add API specification for epoll_pwait2
exec: add API specification for execve
exec: add API specification for execveat
mm/mlock: add API specification for mlock
mm/mlock: add API specification for mlock2
mm/mlock: add API specification for mlockall
mm/mlock: add API specification for munlock
mm/mlock: add API specification for munlockall
kernel/api: add debugfs interface for kernel API specifications
kernel/api: add IOCTL specification infrastructure
fwctl: add detailed IOCTL API specifications
binder: add detailed IOCTL API specifications
tools/kapi: Add kernel API specification extraction tool

Documentation/admin-guide/kernel-api-spec.rst | 699 +++++++++
MAINTAINERS | 9 +
arch/um/kernel/dyn.lds.S | 3 +
arch/um/kernel/uml.lds.S | 3 +
arch/x86/kernel/vmlinux.lds.S | 3 +
drivers/android/binder.c | 758 ++++++++++
drivers/fwctl/main.c | 295 +++-
fs/eventpoll.c | 1056 ++++++++++++++
fs/exec.c | 463 ++++++
include/asm-generic/vmlinux.lds.h | 20 +
include/linux/ioctl_api_spec.h | 540 +++++++
include/linux/kernel_api_spec.h | 942 ++++++++++++
include/linux/syscall_api_spec.h | 341 +++++
include/linux/syscalls.h | 1 +
init/Kconfig | 2 +
kernel/Makefile | 1 +
kernel/api/Kconfig | 55 +
kernel/api/Makefile | 13 +
kernel/api/ioctl_validation.c | 360 +++++
kernel/api/kapi_debugfs.c | 340 +++++
kernel/api/kernel_api_spec.c | 1257 +++++++++++++++++
mm/mlock.c | 646 +++++++++
tools/kapi/.gitignore | 4 +
tools/kapi/Cargo.toml | 19 +
tools/kapi/src/extractor/debugfs.rs | 204 +++
tools/kapi/src/extractor/mod.rs | 95 ++
tools/kapi/src/extractor/source_parser.rs | 488 +++++++
.../src/extractor/vmlinux/binary_utils.rs | 130 ++
tools/kapi/src/extractor/vmlinux/mod.rs | 372 +++++
tools/kapi/src/formatter/json.rs | 170 +++
tools/kapi/src/formatter/mod.rs | 68 +
tools/kapi/src/formatter/plain.rs | 99 ++
tools/kapi/src/formatter/rst.rs | 144 ++
tools/kapi/src/main.rs | 121 ++
34 files changed, 9719 insertions(+), 2 deletions(-)
create mode 100644 Documentation/admin-guide/kernel-api-spec.rst
create mode 100644 include/linux/ioctl_api_spec.h
create mode 100644 include/linux/kernel_api_spec.h
create mode 100644 include/linux/syscall_api_spec.h
create mode 100644 kernel/api/Kconfig
create mode 100644 kernel/api/Makefile
create mode 100644 kernel/api/ioctl_validation.c
create mode 100644 kernel/api/kapi_debugfs.c
create mode 100644 kernel/api/kernel_api_spec.c
create mode 100644 tools/kapi/.gitignore
create mode 100644 tools/kapi/Cargo.toml
create mode 100644 tools/kapi/src/extractor/debugfs.rs
create mode 100644 tools/kapi/src/extractor/mod.rs
create mode 100644 tools/kapi/src/extractor/source_parser.rs
create mode 100644 tools/kapi/src/extractor/vmlinux/binary_utils.rs
create mode 100644 tools/kapi/src/extractor/vmlinux/mod.rs
create mode 100644 tools/kapi/src/formatter/json.rs
create mode 100644 tools/kapi/src/formatter/mod.rs
create mode 100644 tools/kapi/src/formatter/plain.rs
create mode 100644 tools/kapi/src/formatter/rst.rs
create mode 100644 tools/kapi/src/main.rs

--
2.39.5