* [GIT PULL] Kernel API specification framework for v7.4
@ 2026-10-25 16:47 Sasha Levin
0 siblings, 0 replies; only message in thread
From: Sasha Levin @ 2026-10-25 16:47 UTC (permalink / raw)
To: Linus Torvalds
Cc: Sasha Levin, linux-kernel, linux-api, linux-fsdevel, linux-mm,
linux-kbuild, linux-doc, Christian Brauner, Alexander Viro,
Andrew Morton, Jonathan Corbet, Nathan Chancellor,
Nicolas Schier, Thomas Gleixner, Mark Brown, Greg Kroah-Hartman
Hi Linus,
Please consider pulling the kernel API specification framework. It has
been discussed on the lists for over a year: five RFC rounds starting in
June 2025, then v1 through v5 this year, the last on October 8:
https://lore.kernel.org/all/20261008084956.2911790-1-sashal@kernel.org/
The branch has been in linux-next since next-20261009. I held off on
sending this until the first week of the merge window was over, to let
things calm down.
There are two conflicts with what you already merged. linux-next resolved
both the same way:
- Makefile: kbuild added '*.header-check' to the clean rule at the same
spot where this adds '*.apispec.h'. Keep both lines.
- fs/open.c: vfs added filp_close_sync() just above sys_close(), which is
where this adds the sys_close() kerneldoc. Keep filp_close_sync(), then
the new kerneldoc, then the existing "Careful here!" comment and
SYSCALL_DEFINE1(close).
The following changes since commit a90ee4305c4a5df72c11b31dacfdc76e00fcf78a:
Linux 7.3-rc6 (2026-10-04 13:45:25 -0700)
are available in the Git repository at:
https://git.kernel.org/pub/scm/linux/kernel/git/sashal/kapi.git tags/kapi-7.4
for you to fetch changes up to ef777ef05ebcc5ea5393b4bd5af6fc3ad1b3aec9:
kernel/api: add syscall enter/exit tracepoints (2026-10-07 18:26:44 -0400)
----------------------------------------------------------------
Kernel API specification framework for v7.4
The contract of a kernel interface (which arguments are valid, which errors
come back and why, what context it can be called from, what it locks and
what it changes) only exists as prose in man pages and comments, which
tools cannot check. This adds a way to write that contract down in a form
that tools can consume, next to the code it describes.
A spec is structured kerneldoc covering parameter types and constraints,
return values and error codes, execution context, locking, signals,
capabilities and side effects. At build time kernel-doc turns it into C
data in a dedicated section of vmlinux. From there a spec can be:
- checked against syscall arguments and return values at runtime by
CONFIG_KAPI_RUNTIME_CHECKS, a DEBUG_KERNEL option for x86 and arches
without syscall wrappers; a call that violates its spec fails with
-EINVAL before the handler runs
- read as JSON from debugfs
- extracted from vmlinux, debugfs or the source with tools/kapi, which
emits JSON, RST or plain text
- followed with the kapi_syscall_enter/exit tracepoints
The first specs cover open, close, read, write and madvise, with a KUnit
suite and a selftest in tools/testing/selftests/kapi.
Everything is behind CONFIG_KAPI_SPEC, which defaults to off. With it off
the syscall definition macros expand as before, kernel-doc output is
unchanged, and the only change to fs/ and mm/ is the kerneldoc text.
----------------------------------------------------------------
Sasha Levin (11):
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
kernel/api: add API specification for sys_madvise
kernel/api: add syscall enter/exit tracepoints
.gitignore | 1 +
Documentation/dev-tools/index.rst | 1 +
Documentation/dev-tools/kernel-api-spec.rst | 648 +++++
MAINTAINERS | 13 +
Makefile | 1 +
arch/x86/include/asm/syscall_wrapper.h | 3 +-
fs/open.c | 557 ++++
fs/read_write.c | 710 +++++
include/asm-generic/vmlinux.lds.h | 14 +
include/linux/kapi_syscall.h | 35 +
include/linux/kernel_api_spec.h | 1226 ++++++++
include/linux/syscalls.h | 42 +-
include/trace/events/kapi.h | 74 +
init/Kconfig | 2 +
kernel/Makefile | 1 +
kernel/api/Kconfig | 74 +
kernel/api/Makefile | 13 +
kernel/api/internal.h | 25 +
kernel/api/kapi_debugfs.c | 553 ++++
kernel/api/kapi_kunit.c | 720 +++++
kernel/api/kernel_api_spec.c | 1470 ++++++++++
mm/madvise.c | 549 ++++
scripts/Makefile.build | 26 +
tools/docs/kernel-doc | 12 +-
tools/kapi/.gitignore | 3 +
tools/kapi/Cargo.lock | 679 +++++
tools/kapi/Cargo.toml | 20 +
tools/kapi/Makefile | 33 +
tools/kapi/README.md | 33 +
tools/kapi/src/extractor/debugfs.rs | 1704 +++++++++++
tools/kapi/src/extractor/kerneldoc_parser.rs | 3335 ++++++++++++++++++++++
tools/kapi/src/extractor/mod.rs | 442 +++
tools/kapi/src/extractor/source_parser.rs | 531 ++++
tools/kapi/src/extractor/vmlinux/binary_utils.rs | 461 +++
tools/kapi/src/extractor/vmlinux/mod.rs | 1160 ++++++++
tools/kapi/src/formatter/json.rs | 659 +++++
tools/kapi/src/formatter/mod.rs | 220 ++
tools/kapi/src/formatter/plain.rs | 679 +++++
tools/kapi/src/formatter/rst.rs | 802 ++++++
tools/kapi/src/main.rs | 123 +
tools/lib/python/kdoc/kdoc_apispec.py | 1391 +++++++++
tools/lib/python/kdoc/kdoc_files.py | 12 +-
tools/lib/python/kdoc/kdoc_parser.py | 101 +-
tools/testing/selftests/Makefile | 1 +
tools/testing/selftests/kapi/.gitignore | 2 +
tools/testing/selftests/kapi/Makefile | 7 +
tools/testing/selftests/kapi/kapi_test_util.h | 31 +
tools/testing/selftests/kapi/test_kapi.c | 1163 ++++++++
48 files changed, 20350 insertions(+), 12 deletions(-)
create mode 100644 Documentation/dev-tools/kernel-api-spec.rst
create mode 100644 include/linux/kapi_syscall.h
create mode 100644 include/linux/kernel_api_spec.h
create mode 100644 include/trace/events/kapi.h
create mode 100644 kernel/api/Kconfig
create mode 100644 kernel/api/Makefile
create mode 100644 kernel/api/internal.h
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.lock
create mode 100644 tools/kapi/Cargo.toml
create mode 100644 tools/kapi/Makefile
create mode 100644 tools/kapi/README.md
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/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/.gitignore
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
--
Thanks,
Sasha
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2026-10-25 16:47 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2026-10-25 16:47 [GIT PULL] Kernel API specification framework for v7.4 Sasha Levin
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®