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
