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 represents a fundamental shift from macro-based API specifications to kerneldoc integration. Instead of requiring developers to write specifications using C macros separate from documentation, the framework now leverages the existing kerneldoc infrastructure. This unification means developers write API specifications as part of their regular documentation workflow, with the build system automatically generating machine-readable C macros from these comments. Changes since RFC v2: 1. Kerneldoc Integration: transition from C macros to kerneldoc comments. 2. Structured Parameter Specifications: Support for complex data structures with field-level constraints, including ranges, enums, and validation groups. 3. Hybrid Documentation Approach: Core API specifications remain inline with the implementation for tight coupling, while extended documentation (examples, detailed notes, complex constraints) can be maintained in separate files under Documentation/. Sasha Levin (4): kernel/api: introduce kernel API specification framework kernel/api: enable kerneldoc-based API specifications mm/mlock: add API specification for mlock kernel/sched: add specs for sys_sched_setattr() Documentation/admin-guide/kernel-api-spec.rst | 507 ++++++ Documentation/userspace-api/syscalls/mlock.rst| 118 ++ MAINTAINERS | 9 + arch/um/kernel/dyn.lds.S | 3 + arch/um/kernel/uml.lds.S | 3 + arch/x86/kernel/vmlinux.lds.S | 3 + include/asm-generic/vmlinux.lds.h | 20 + include/linux/kernel_api_spec.h | 1527 +++++++++++++++++ include/linux/syscall_api_spec.h | 137 ++ include/linux/syscalls.h | 38 + init/Kconfig | 2 + kernel/Makefile | 1 + kernel/api/Kconfig | 35 + kernel/api/Makefile | 26 + kernel/api/kernel_api_spec.c | 1122 ++++++++++++ kernel/sched/syscalls.c | 168 +- mm/mlock.c | 85 + scripts/Makefile.build | 28 + scripts/generate_api_specs.sh | 59 + scripts/kernel-doc.py | 5 + scripts/lib/kdoc/kdoc_apispec.py | 623 +++++++ scripts/lib/kdoc/kdoc_output.py | 5 +- scripts/lib/kdoc/kdoc_parser.py | 54 +- 23 files changed, 4574 insertions(+), 4 deletions(-) create mode 100644 Documentation/admin-guide/kernel-api-spec.rst create mode 100644 Documentation/userspace-api/syscalls/mlock.rst 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/kernel_api_spec.c create mode 100755 scripts/generate_api_specs.sh create mode 100644 scripts/lib/kdoc/kdoc_apispec.py -- 2.39.5
