From: Sasha Levin <sashal@kernel.org>
To: linux-api@vger.kernel.org, linux-kernel@vger.kernel.org
Cc: linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org,
linux-kbuild@vger.kernel.org, linux-kselftest@vger.kernel.org,
workflows@vger.kernel.org, tools@kernel.org, x86@kernel.org,
Thomas Gleixner <tglx@kernel.org>,
"Paul E. McKenney" <paulmck@kernel.org>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
Jonathan Corbet <corbet@lwn.net>,
Dmitry Vyukov <dvyukov@google.com>,
Randy Dunlap <rdunlap@infradead.org>,
Cyril Hrubis <chrubis@suse.cz>, Kees Cook <kees@kernel.org>,
Jake Edge <jake@lwn.net>,
David Laight <david.laight.linux@gmail.com>,
Askar Safin <safinaskar@zohomail.com>,
Gabriele Paoloni <gpaoloni@redhat.com>,
Mauro Carvalho Chehab <mchehab@kernel.org>,
Christian Brauner <brauner@kernel.org>,
Alexander Viro <viro@zeniv.linux.org.uk>,
Andrew Morton <akpm@linux-foundation.org>,
Masahiro Yamada <masahiroy@kernel.org>,
Shuah Khan <skhan@linuxfoundation.org>,
Ingo Molnar <mingo@redhat.com>, Arnd Bergmann <arnd@arndb.de>,
Sasha Levin <sashal@kernel.org>
Subject: [PATCH 0/9] Kernel API Specification Framework
Date: Fri, 13 Mar 2026 11:09:10 -0400 [thread overview]
Message-ID: <20260313150928.2637368-1-sashal@kernel.org> (raw)
This proposal introduces machinery for documenting kernel APIs, addressing the
long-standing challenge of maintaining stable interfaces between the kernel and
user-space programs. Despite the kernel's commitment to never breaking user
space, the lack of machine-readable API specifications has led to breakages and
across system calls and IOCTLs.
Specifications can document parameter types, valid ranges, constraints, and
alignment requirements. They capture return value semantics including success
conditions and error codes with their meaning. Execution context requirements,
capabilities, locking constraints, signal handling behavior, and side effects
can all be formally specified.
These specifications live alongside the code they document and are both
human-readable and machine-parseable. They can be validated at runtime when
CONFIG_KAPI_RUNTIME_CHECKS is enabled, exported via debugfs for userspace
tools, and extracted from either vmlinux or source code.
This enables static analysis tools to verify userspace API usage at compile
time, test generation based on formal specifications, consistent error handling
validation, automated documentation generation, and formal verification of
kernel interfaces.
The implementation includes a core framework with ELF section storage,
kerneldoc integration for inline specification, a debugfs interface for runtime
querying, and a Rust-based extraction tool (tools/kapi) supporting JSON, RST,
and plain text output formats. Example specifications are provided for the four
fundamental file syscalls (sys_open, sys_close, sys_read, sys_write). The
series also includes a KUnit test suite with 38 tests and a runtime
verification selftest with 29+ TAP tests.
The series with runtime testing enabled (CONFIG_KAPI_RUNTIME_CHECKS=y)
currently survives LTP tests in a KVM VM.
Changes since RFC v5:
- Streamlined example specs: focus on open/close/read/write to start with.
- Added KUnit test suite.
- Added runtime verification selftest.
- Fixed kernel test robot warnings from v5: fixed "document isn't included in
any toctree" (kernel-api-spec.rst now properly added to
Documentation/dev-tools/index.rst), fixed sparse "non size-preserving
integer to pointer cast" warnings in kernel_api_spec.c.
- Rebased on v7.0-rc1.
References:
RFC v5: https://lore.kernel.org/lkml/20251218204239.4159453-1-sashal@kernel.org/
RFC v4: https://lore.kernel.org/lkml/20250825181434.3340805-1-sashal@kernel.org/
RFC v3: https://lore.kernel.org/lkml/20250711114248.2288591-1-sashal@kernel.org/
RFC v2: https://lore.kernel.org/lkml/20250624180742.5795-1-sashal@kernel.org/
RFC v1: https://lore.kernel.org/lkml/20250614134858.790460-1-sashal@kernel.org/
Sasha Levin (9):
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
.gitignore | 1 +
Documentation/dev-tools/index.rst | 1 +
Documentation/dev-tools/kernel-api-spec.rst | 629 +++++++
MAINTAINERS | 12 +
arch/x86/include/asm/syscall_wrapper.h | 40 +
fs/open.c | 576 +++++-
fs/read_write.c | 687 +++++++
include/asm-generic/vmlinux.lds.h | 28 +
include/linux/kernel_api_spec.h | 1580 +++++++++++++++++
include/linux/syscall_api_spec.h | 192 ++
include/linux/syscalls.h | 39 +
init/Kconfig | 2 +
kernel/Makefile | 3 +
kernel/api/.gitignore | 2 +
kernel/api/Kconfig | 70 +
kernel/api/Makefile | 14 +
kernel/api/kapi_debugfs.c | 503 ++++++
kernel/api/kapi_kunit.c | 536 ++++++
kernel/api/kernel_api_spec.c | 1277 +++++++++++++
scripts/Makefile.build | 31 +
scripts/Makefile.clean | 3 +
tools/docs/kernel-doc | 5 +
tools/kapi/.gitignore | 4 +
tools/kapi/Cargo.toml | 19 +
tools/kapi/src/extractor/debugfs.rs | 581 ++++++
tools/kapi/src/extractor/kerneldoc_parser.rs | 1554 ++++++++++++++++
tools/kapi/src/extractor/mod.rs | 463 +++++
tools/kapi/src/extractor/source_parser.rs | 405 +++++
.../src/extractor/vmlinux/binary_utils.rs | 505 ++++++
.../src/extractor/vmlinux/magic_finder.rs | 112 ++
tools/kapi/src/extractor/vmlinux/mod.rs | 842 +++++++++
tools/kapi/src/formatter/json.rs | 727 ++++++++
tools/kapi/src/formatter/mod.rs | 140 ++
tools/kapi/src/formatter/plain.rs | 708 ++++++++
tools/kapi/src/formatter/rst.rs | 852 +++++++++
tools/kapi/src/main.rs | 119 ++
tools/lib/python/kdoc/kdoc_apispec.py | 887 +++++++++
tools/lib/python/kdoc/kdoc_output.py | 9 +-
tools/lib/python/kdoc/kdoc_parser.py | 86 +-
tools/testing/selftests/kapi/Makefile | 7 +
tools/testing/selftests/kapi/kapi_test_util.h | 31 +
tools/testing/selftests/kapi/test_kapi.c | 1021 +++++++++++
42 files changed, 15294 insertions(+), 9 deletions(-)
create mode 100644 Documentation/dev-tools/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/.gitignore
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/kapi_kunit.c
create mode 100644 kernel/api/kernel_api_spec.c
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/main.rs
create mode 100644 tools/lib/python/kdoc/kdoc_apispec.py
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
--
2.51.0
next reply other threads:[~2026-03-13 15:09 UTC|newest]
Thread overview: 37+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-03-13 15:09 Sasha Levin [this message]
2026-03-13 15:09 ` [PATCH 1/9] kernel/api: introduce kernel API specification framework Sasha Levin
2026-03-17 17:49 ` Jonathan Corbet
2026-03-18 6:00 ` Mauro Carvalho Chehab
2026-03-18 14:53 ` Sasha Levin
2026-03-18 14:30 ` Sasha Levin
2026-03-18 16:50 ` Jonathan Corbet
2026-03-18 14:32 ` Sasha Levin
2026-03-18 16:51 ` Jonathan Corbet
2026-03-13 15:09 ` [PATCH 2/9] kernel/api: enable kerneldoc-based API specifications Sasha Levin
2026-03-13 15:09 ` [PATCH 3/9] kernel/api: add debugfs interface for kernel " Sasha Levin
2026-03-13 15:32 ` Greg Kroah-Hartman
2026-03-13 16:27 ` Sasha Levin
2026-03-13 15:09 ` [PATCH 4/9] tools/kapi: Add kernel API specification extraction tool Sasha Levin
2026-03-13 15:09 ` [PATCH 5/9] kernel/api: add API specification for sys_open Sasha Levin
2026-03-13 15:33 ` Greg Kroah-Hartman
2026-03-13 16:42 ` Sasha Levin
2026-03-17 18:37 ` Jonathan Corbet
2026-03-18 14:12 ` Sasha Levin
2026-03-18 14:16 ` Jonathan Corbet
2026-03-13 15:09 ` [PATCH 6/9] kernel/api: add API specification for sys_close Sasha Levin
2026-03-13 15:49 ` Greg Kroah-Hartman
2026-03-13 16:46 ` Sasha Levin
2026-03-13 15:52 ` Greg Kroah-Hartman
2026-03-13 16:55 ` Sasha Levin
2026-03-13 15:09 ` [PATCH 7/9] kernel/api: add API specification for sys_read Sasha Levin
2026-03-13 15:09 ` [PATCH 8/9] kernel/api: add API specification for sys_write Sasha Levin
2026-03-13 15:09 ` [PATCH 9/9] kernel/api: add runtime verification selftest Sasha Levin
2026-03-14 18:18 ` [PATCH 0/9] Kernel API Specification Framework Jakub Kicinski
2026-03-14 22:44 ` David Laight
2026-03-15 6:46 ` Sasha Levin
2026-03-15 6:36 ` Sasha Levin
2026-03-18 6:24 ` Mauro Carvalho Chehab
2026-03-18 14:14 ` Sasha Levin
2026-03-16 7:05 ` Dmitry Vyukov
2026-03-16 22:57 ` Jakub Kicinski
2026-03-16 23:29 ` Sasha Levin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20260313150928.2637368-1-sashal@kernel.org \
--to=sashal@kernel.org \
--cc=akpm@linux-foundation.org \
--cc=arnd@arndb.de \
--cc=brauner@kernel.org \
--cc=chrubis@suse.cz \
--cc=corbet@lwn.net \
--cc=david.laight.linux@gmail.com \
--cc=dvyukov@google.com \
--cc=gpaoloni@redhat.com \
--cc=gregkh@linuxfoundation.org \
--cc=jake@lwn.net \
--cc=kees@kernel.org \
--cc=linux-api@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kbuild@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=masahiroy@kernel.org \
--cc=mchehab@kernel.org \
--cc=mingo@redhat.com \
--cc=paulmck@kernel.org \
--cc=rdunlap@infradead.org \
--cc=safinaskar@zohomail.com \
--cc=skhan@linuxfoundation.org \
--cc=tglx@kernel.org \
--cc=tools@kernel.org \
--cc=viro@zeniv.linux.org.uk \
--cc=workflows@vger.kernel.org \
--cc=x86@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox