Skip to content

RFC Kernel API Specification Framework

Sasha Levin linux-api linux-doc lkml tools 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v4 RFC Latest7 patches 1 replyIn review

Changes in v4 from the cover letter

1. Improved kerneldoc format for better readability.

2. Added kerneldoc parsing support in the kapi tool.

3. Use magic markers in the binary output to simplify extraction.

Patches in v4 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/7kernel/api: introduce kernel API specification framework.gitignore Documentation/admin-guide/kernel-api-spec.rst MAINTAINERS +12 more+3468 -01 reply
2/7kernel/api: enable kerneldoc-based API specificationskernel/api/Makefile scripts/Makefile.build scripts/generate_api_specs.sh +4 more+891 -50 replies
3/7kernel/api: add debugfs interface for kernel API specificationskernel/api/Kconfig kernel/api/Makefile kernel/api/kapi_debugfs.c+359 -10 replies
4/7kernel/sched: add specs for sys_sched_setattr()kernel/sched/syscalls.c+314 -10 replies
5/7mm/mlock: add API specification for mlockmm/mlock.c+134 -00 replies
6/7fs/exec: add API specification for execveatfs/exec.c+594 -00 replies
7/7tools/kapi: Add kernel API specification extraction toolDocumentation/admin-guide/kernel-api-spec.rst tools/kapi/.gitignore tools/kapi/Cargo.toml +13 more+5978 -30 replies

Reviews trailers per patch

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

Read the v4 thread

Cover letter [RFC PATCH v4 0/7] Kernel API Specification Framework

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.

Changes since RFC v3:

1. Improved kerneldoc format for better readability.

2. Added kerneldoc parsing support in the kapi tool.

3. Use magic markers in the binary output to simplify extraction.

Sasha Levin (7):
kernel/api: introduce kernel API specification framework kernel/api: enable kerneldoc-based API specifications kernel/api: add debugfs interface for kernel API specifications kernel/sched: add specs for sys_sched_setattr() mm/mlock: add API specification for mlock
fs/exec: add API specification for execveat tools/kapi: Add kernel API specification extraction tool

 .gitignore                                    |    1 +
 Documentation/admin-guide/kernel-api-spec.rst |  699 ++++++++
 MAINTAINERS                                   |    9 +
 arch/um/kernel/dyn.lds.S                      |    3 +
 arch/um/kernel/uml.lds.S                      |    3 +
 arch/x86/kernel/vmlinux.lds.S                 |    3 +
 fs/exec.c                                     |  594 +++++++
 include/asm-generic/vmlinux.lds.h             |   20 +
 include/linux/kernel_api_spec.h               | 1559 +++++++++++++++++
 include/linux/syscall_api_spec.h              |  125 ++
 include/linux/syscalls.h                      |   38 +
 init/Kconfig                                  |    2 +
 kernel/Makefile                               |    1 +
 kernel/api/Kconfig                            |   55 +
 kernel/api/Makefile                           |   30 +
 kernel/api/kapi_debugfs.c                     |  334 ++++
 kernel/api/kernel_api_spec.c                  | 1155 ++++++++++++
 kernel/sched/syscalls.c                       |  315 +++-
 mm/mlock.c                                    |  134 ++
 scripts/Makefile.build                        |   28 +
 scripts/generate_api_specs.sh                 |   68 +
 scripts/kernel-doc.py                         |    5 +
 scripts/lib/kdoc/kdoc_apispec.py              |  714 ++++++++
 scripts/lib/kdoc/kdoc_output.py               |    9 +-
 scripts/lib/kdoc/kdoc_parser.py               |   50 +-
 tools/kapi/.gitignore                         |    4 +
 tools/kapi/Cargo.toml                         |   19 +
 tools/kapi/src/extractor/debugfs.rs           |  442 +++++
 tools/kapi/src/extractor/kerneldoc_parser.rs  |  694 ++++++++
 tools/kapi/src/extractor/mod.rs               |  461 +++++
 tools/kapi/src/extractor/source_parser.rs     |  213 +++
 .../src/extractor/vmlinux/binary_utils.rs     |  180 ++
 .../src/extractor/vmlinux/magic_finder.rs     |  102 ++
 tools/kapi/src/extractor/vmlinux/mod.rs       |  869 +++++++++
 tools/kapi/src/formatter/json.rs              |  468 +++++
 tools/kapi/src/formatter/mod.rs               |  145 ++
 tools/kapi/src/formatter/plain.rs             |  558 ++++++
 tools/kapi/src/formatter/rst.rs               |  621 +++++++
 tools/kapi/src/formatter/shall.rs             |  891 ++++++++++
 tools/kapi/src/main.rs                        |  116 ++
 40 files changed, 11732 insertions(+), 5 deletions(-)
 create mode 100644 Documentation/admin-guide/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/Kconfig
 create mode 100644 kernel/api/Makefile
 create mode 100644 kernel/api/kapi_debugfs.c
 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
 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/formatter/shall.rs
 create mode 100644 tools/kapi/src/main.rs
Signature · 1 line
2.50.1