After going through five rounds of review under a Request For Comments (RFC) flag, today the latest round of Kernel API Specification Framework patches were sent out with the RFC flag removed.
The Kernel API Specification Framework aims to better document the kernel APIs in both human-readable and machine-readable form. Sasha Levin explains in the patch series cover letter:
“This proposal introduces machinery for documenting kernel APIs, addressing the long-standing challenge of maintaining stable interfaces between the kernel and user-space programs. Despite the kernel’s commitment to never breaking user space, the lack of machine-readable API specifications has led to breakages and across system calls and IOCTLs.
Specifications can document parameter types, valid ranges, constraints, and alignment requirements. They capture return value semantics including success conditions and error codes with their meaning. Execution context requirements, capabilities, locking constraints, signal handling behavior, and side effects can all be formally specified.
These specifications live alongside the code they document and are both human-readable and machine-parseable. They can be validated at runtime when CONFIG_KAPI_RUNTIME_CHECKS is enabled, exported via debugfs for userspace tools, and extracted from either vmlinux or source code.
This enables static analysis tools to verify userspace API usage at compile time, test generation based on formal specifications, consistent error handling validation, automated documentation generation, and formal verification of kernel interfaces.
The implementation includes a core framework with ELF section storage, kerneldoc integration for inline specification, a debugfs interface for runtime querying, and a Rust-based extraction tool (tools/kapi) supporting JSON, RST, and plain text output formats. Example specifications are provided for the four fundamental file syscalls (sys_open, sys_close, sys_read, sys_write). The series also includes a KUnit test suite with 38 tests and a runtime verification selftest with 29+ TAP tests.”
Today’s patches besides dropping the RFC banner have now been re-based against the Linux 7.0-rc1 state, KUnit test suite coverage, streamlined example specs, and run-time verification selftests.
