[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Message-Id: <20250711114248.2288591-1-sashal@kernel.org>
Date: Fri, 11 Jul 2025 07:42:44 -0400
From: Sasha Levin <sashal@...nel.org>
To: linux-kernel@...r.kernel.org
Cc: linux-doc@...r.kernel.org,
linux-api@...r.kernel.org,
tools@...nel.org,
Sasha Levin <sashal@...nel.org>
Subject: [RFC v3 0/4] Kernel API Specification Framework with kerneldoc integration
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
Powered by blists - more mailing lists