Sasha Levin just sent out an initial “request for comments” patch series for the Linux kernel in aiming to establish a Kernel API Specification Framework.
Sasha’s cover letter does a good job describing this proposed Kernel API Specification Framework to formalize the kernel APIs exposed to user-space:
“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.”
It will be very interesting to see where this Kernel API Specification Framework leads but for now those interested can learn more via the RFC patch series.
