[RFC v3 0/4] Kernel API Specification Framework with kerneldoc integration

[Sasha Levin <sashal@kernel.org>]

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