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. The series with runtime testing enabled (CONFIG_KAPI_RUNTIME_CHECKS=y) currently survives LTP tests in a KVM VM. Changes since v1: - Removed DEFINE_KERNEL_API_SPEC macro from user-facing documentation and examples. The macros are now internal plumbing only; kerneldoc annotations are the sole authoring interface. (Jonathan Corbet, Mauro Carvalho Chehab) - Removed IOCTL specification section from documentation, as no IOCTL specs are included in this series. (Jonathan Corbet) - Removed since-version field entirely from the framework: struct kernel_api_spec, debugfs output, JSON export, kdoc parser, and all extractors/formatters in the kapi tool. (Jonathan Corbet) - Removed stale :Date: field from documentation. (Jonathan Corbet) - Fixed kmalloc documentation example to include both parameters (size and flags) and a side-effect entry, matching the output example. (Jonathan Corbet) - Simplified DSL references in documentation: converted Common Patterns section from raw macros to kerneldoc annotation format, removed macro references from Implementation Details and Troubleshooting. (Jonathan Corbet, Mauro Carvalho Chehab) - Reworded sys_close spec to describe behavior without referencing kernel internal callbacks: "flush callback" replaced with "close-time flush operation", "release callback" references removed entirely. (Greg Kroah-Hartman) - Removed HP-UX reference and "implementation-defined behavior" phrasing from sys_close spec. (Greg Kroah-Hartman) - Added copyright lines to all new files: C headers, kernel modules, Python scripts, Rust source files, and selftests. (Greg Kroah-Hartman) - Fixed rebasing artifact where patch 3 removed content from patch 1's documentation additions. (Greg Kroah-Hartman) - Removed unnecessary pr_info() from debugfs init and braces from single-line for loop. (Greg Kroah-Hartman) - Added commit message changelogs to all patches. (Greg Kroah-Hartman) References: v1: https://lore.kernel.org/all/[email protected]/ RFC v5: https://lore.kernel.org/lkml/[email protected]/ RFC v4: https://lore.kernel.org/lkml/[email protected]/ RFC v3: https://lore.kernel.org/lkml/[email protected]/ RFC v2: https://lore.kernel.org/lkml/[email protected]/ RFC v1: https://lore.kernel.org/lkml/[email protected]/ Sasha Levin (9): kernel/api: introduce kernel API specification framework kernel/api: enable kerneldoc-based API specifications kernel/api: add debugfs interface for kernel API specifications tools/kapi: Add kernel API specification extraction tool kernel/api: add API specification for sys_open kernel/api: add API specification for sys_close kernel/api: add API specification for sys_read kernel/api: add API specification for sys_write kernel/api: add runtime verification selftest .gitignore | 1 + Documentation/dev-tools/index.rst | 1 + Documentation/dev-tools/kernel-api-spec.rst | 620 +++++++ MAINTAINERS | 12 + arch/x86/include/asm/syscall_wrapper.h | 40 + fs/open.c | 565 +++++- fs/read_write.c | 683 +++++++ include/asm-generic/vmlinux.lds.h | 28 + include/linux/kernel_api_spec.h | 1580 +++++++++++++++++ include/linux/syscall_api_spec.h | 186 ++ include/linux/syscalls.h | 39 + init/Kconfig | 2 + kernel/Makefile | 3 + kernel/api/.gitignore | 2 + kernel/api/Kconfig | 70 + kernel/api/Makefile | 14 + kernel/api/kapi_debugfs.c | 499 ++++++ kernel/api/kapi_kunit.c | 538 ++++++ kernel/api/kernel_api_spec.c | 1277 +++++++++++++ scripts/Makefile.build | 31 + scripts/Makefile.clean | 3 + tools/docs/kernel-doc | 5 + tools/kapi/.gitignore | 4 + tools/kapi/Cargo.toml | 19 + tools/kapi/src/extractor/debugfs.rs | 578 ++++++ tools/kapi/src/extractor/kerneldoc_parser.rs | 1555 ++++++++++++++++ tools/kapi/src/extractor/mod.rs | 461 +++++ tools/kapi/src/extractor/source_parser.rs | 408 +++++ .../src/extractor/vmlinux/binary_utils.rs | 508 ++++++ .../src/extractor/vmlinux/magic_finder.rs | 115 ++ tools/kapi/src/extractor/vmlinux/mod.rs | 844 +++++++++ tools/kapi/src/formatter/json.rs | 720 ++++++++ tools/kapi/src/formatter/mod.rs | 142 ++ tools/kapi/src/formatter/plain.rs | 707 ++++++++ tools/kapi/src/formatter/rst.rs | 850 +++++++++ tools/kapi/src/main.rs | 122 ++ tools/lib/python/kdoc/kdoc_apispec.py | 888 +++++++++ tools/lib/python/kdoc/kdoc_output.py | 9 +- tools/lib/python/kdoc/kdoc_parser.py | 85 +- tools/testing/selftests/kapi/Makefile | 7 + tools/testing/selftests/kapi/kapi_test_util.h | 33 + tools/testing/selftests/kapi/test_kapi.c | 1023 +++++++++++ 42 files changed, 15268 insertions(+), 9 deletions(-) create mode 100644 Documentation/dev-tools/kernel-api-spec.rst create mode 100644 include/linux/kernel_api_spec.h create mode 100644 include/linux/syscall_api_spec.h create mode 100644 kernel/api/.gitignore create mode 100644 kernel/api/Kconfig create mode 100644 kernel/api/Makefile create mode 100644 kernel/api/kapi_debugfs.c create mode 100644 kernel/api/kapi_kunit.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/kerneldoc_parser.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/magic_finder.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 create mode 100644 tools/lib/python/kdoc/kdoc_apispec.py create mode 100644 tools/testing/selftests/kapi/Makefile create mode 100644 tools/testing/selftests/kapi/kapi_test_util.h create mode 100644 tools/testing/selftests/kapi/test_kapi.c -- 2.51.0
