Re: [GIT PULL] Kernel API specification framework for v7.4
From: Sasha Levin
Date: Mon Nov 16 2026 - 13:14:38 EST
Ping?
On Sun, Oct 25, 2026 at 12:47 PM Sasha Levin <sashal@xxxxxxxxxx> wrote:
>
> 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@xxxxxxxxxx/
>
> 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