Skip to content

RFC Kernel API Specification Framework with kerneldoc integration

Sasha Levin linux-api linux-doc lkml llvm oe-kbuild-all tools 3 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v3 RFC Latest4 patches 5 repliesIn review
  2. v2 RFC22 patches 10 repliesSuperseded
  3. v1 RFC19 patches 24 repliesSuperseded

Changes in v3 from the cover letter

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/.

Patches in v3 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/4kernel/api: introduce kernel API specification frameworkDocumentation/admin-guide/kernel-api-spec.rst MAINTAINERS arch/um/kernel/dyn.lds.S +11 more+3414 -02 replies
2/4kernel/api: enable kerneldoc-based API specificationskernel/api/Makefile scripts/Makefile.build scripts/generate_api_specs.sh +4 more+791 -43 replies
3/4mm/mlock: add API specification for mlockmm/mlock.c+85 -00 replies
4/4kernel/sched: add specs for sys_sched_setattr()kernel/sched/syscalls.c+167 -10 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v3 yet.

Read the v3 thread

Cover letter [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
Signature · 1 line
2.39.5