From: Sasha Levin <sashal@kernel.org>
To: linux-api@vger.kernel.org, linux-kernel@vger.kernel.org
Cc: Sasha Levin <sashal@kernel.org>,
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>,
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>,
Arnd Bergmann <arnd@arndb.de>,
Nathan Chancellor <nathan@kernel.org>,
Steven Rostedt <rostedt@goodmis.org>,
Masami Hiramatsu <mhiramat@kernel.org>,
Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Subject: [PATCH v5 04/11] tools/kapi: add kernel API specification extraction tool
Date: Thu, 8 Oct 2026 04:49:44 -0400 [thread overview]
Message-ID: <20261008084956.2911790-5-sashal@kernel.org> (raw)
In-Reply-To: <20261008084956.2911790-1-sashal@kernel.org>
The kapi tool extracts and renders kernel API specifications from
three input sources and emits them in one of three output formats:
Input modes:
--source PATH parse kerneldoc blocks from a C source file or
directory
--vmlinux PATH decode the `.kapi_specs` ELF section from a
compiled kernel binary
--debugfs PATH read the spec dumps exposed under
/sys/kernel/debug/kapi/ on a running kernel
Output formats: plain, json, rst
The tool is written in Rust and builds with cargo from the crates
pinned in Cargo.lock; the resulting binary has no runtime
dependencies. It ships alongside the kernel to give documentation
tools, static analyzers, and IDE integrations a single entry point for
querying the spec data produced by the framework.
Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
Documentation/dev-tools/kernel-api-spec.rst | 74 +-
tools/kapi/.gitignore | 3 +
tools/kapi/Cargo.lock | 679 ++++
tools/kapi/Cargo.toml | 20 +
tools/kapi/Makefile | 33 +
tools/kapi/README.md | 33 +
| 1704 +++++++++
| 3335 +++++++++++++++++
| 442 +++
| 531 +++
| 461 +++
| 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 +
17 files changed, 10886 insertions(+), 72 deletions(-)
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
diff --git a/Documentation/dev-tools/kernel-api-spec.rst b/Documentation/dev-tools/kernel-api-spec.rst
index fa8aabb92a503..95b72060f8ef8 100644
--- a/Documentation/dev-tools/kernel-api-spec.rst
+++ b/Documentation/dev-tools/kernel-api-spec.rst
@@ -31,7 +31,8 @@ The framework aims to:
common programming errors during development and testing.
3. **Support Tooling**: Export API specifications in machine-readable formats for
- use by static analyzers, documentation generators, and development tools.
+ use by static analyzers, documentation generators, and development tools. See
+ `The kapi Tool`_.
4. **Formalize Contracts**: Explicitly document API contracts including parameter
constraints, execution contexts, locking requirements, and side effects.
@@ -573,77 +574,6 @@ The tool supports all KAPI specification types:
- System calls (kerneldoc annotations)
- Kernel functions (kerneldoc annotations with KAPI tags)
-IDE Integration
----------------
-
-Modern IDEs can use the specification data for:
-
-- Parameter hints
-- Type checking
-- Context validation
-- Error code documentation
-
-Best Practices
-==============
-
-Writing Specifications
-----------------------
-
-1. **Be Comprehensive**: Document all parameters, errors, and side effects
-2. **Keep Updated**: Update specs when API behavior changes
-3. **Use Examples**: Include usage examples in descriptions
-4. **Validate Constraints**: Define realistic constraints for parameters
-5. **Document Context**: Clearly specify allowed execution contexts
-
-Maintenance
------------
-
-1. **Version Specifications**: Increment version when API changes
-2. **Deprecation**: Mark deprecated APIs and suggest replacements
-3. **Cross-reference**: Link related APIs in descriptions
-4. **Test Specifications**: Verify specs match implementation
-
-Common Patterns
----------------
-
-**Optional Parameters**:
-
-.. code-block:: c
-
- /**
- * @optional_arg: Optional argument (may be NULL)
- *
- * param: optional_arg
- * type: KAPI_TYPE_PTR
- * flags: KAPI_PARAM_IN | KAPI_PARAM_OPTIONAL
- */
-
-**Buffer with Size Parameter**:
-
-.. code-block:: c
-
- /**
- * @buf: User-space buffer
- *
- * param: buf
- * type: KAPI_TYPE_USER_PTR
- * flags: KAPI_PARAM_OUT | KAPI_PARAM_USER
- * constraint-type: KAPI_CONSTRAINT_BUFFER
- * size-param: 2
- */
-
-**Callback Functions**:
-
-.. code-block:: c
-
- /**
- * @callback: Callback function
- *
- * param: callback
- * type: KAPI_TYPE_FUNC_PTR
- * flags: KAPI_PARAM_IN
- */
-
Troubleshooting
===============
diff --git a/tools/kapi/.gitignore b/tools/kapi/.gitignore
new file mode 100644
index 0000000000000..fa95032ed6c2a
--- /dev/null
+++ b/tools/kapi/.gitignore
@@ -0,0 +1,3 @@
+# Rust build artifacts
+/target/
+**/*.rs.bk
diff --git a/tools/kapi/Cargo.lock b/tools/kapi/Cargo.lock
new file mode 100644
index 0000000000000..23d4ef8b910d2
--- /dev/null
+++ b/tools/kapi/Cargo.lock
@@ -0,0 +1,679 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys",
+]
+
+[[package]]
+name = "anyhow"
+version = "1.0.102"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+
+[[package]]
+name = "bitflags"
+version = "2.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "clap"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
+
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
+[[package]]
+name = "getrandom"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+ "wasip2",
+ "wasip3",
+]
+
+[[package]]
+name = "goblin"
+version = "0.10.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "983a6aafb3b12d4c41ea78d39e189af4298ce747353945ff5105b54a056e5cd9"
+dependencies = [
+ "log",
+ "plain",
+ "scroll",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f467dd6dccf739c208452f8014c75c18bb8301b050ad1cfb27153803edb0f51"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "id-arena"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown 0.17.0",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "kapi"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "clap",
+ "goblin",
+ "regex",
+ "serde",
+ "serde_json",
+ "tempfile",
+ "walkdir",
+]
+
+[[package]]
+name = "leb128fmt"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
+
+[[package]]
+name = "libc"
+version = "0.2.185"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "log"
+version = "0.4.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
+
+[[package]]
+name = "memchr"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "plain"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6"
+
+[[package]]
+name = "prettyplease"
+version = "0.2.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
+dependencies = [
+ "proc-macro2",
+ "syn",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "regex"
+version = "1.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "scroll"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c1257cd4248b4132760d6524d6dda4e053bc648c9070b960929bf50cfb1e7add"
+dependencies = [
+ "scroll_derive",
+]
+
+[[package]]
+name = "scroll_derive"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed76efe62313ab6610570951494bdaa81568026e0318eaa55f167de70eeea67d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.149"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom",
+ "once_cell",
+ "rustix",
+ "windows-sys",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-xid"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
+[[package]]
+name = "wasip2"
+version = "1.0.3+wasi-0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20064672db26d7cdc89c7798c48a0fdfac8213434a1186e5ef29fd560ae223d6"
+dependencies = [
+ "wit-bindgen 0.57.1",
+]
+
+[[package]]
+name = "wasip3"
+version = "0.4.0+wasi-0.3.0-rc-2026-01-06"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5"
+dependencies = [
+ "wit-bindgen 0.51.0",
+]
+
+[[package]]
+name = "wasm-encoder"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "990065f2fe63003fe337b932cfb5e3b80e0b4d0f5ff650e6985b1048f62c8319"
+dependencies = [
+ "leb128fmt",
+ "wasmparser",
+]
+
+[[package]]
+name = "wasm-metadata"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909"
+dependencies = [
+ "anyhow",
+ "indexmap",
+ "wasm-encoder",
+ "wasmparser",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
+dependencies = [
+ "bitflags",
+ "hashbrown 0.15.5",
+ "indexmap",
+ "semver",
+]
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"
+dependencies = [
+ "wit-bindgen-rust-macro",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "wit-bindgen-core"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea61de684c3ea68cb082b7a88508a8b27fcc8b797d738bfc99a82facf1d752dc"
+dependencies = [
+ "anyhow",
+ "heck",
+ "wit-parser",
+]
+
+[[package]]
+name = "wit-bindgen-rust"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21"
+dependencies = [
+ "anyhow",
+ "heck",
+ "indexmap",
+ "prettyplease",
+ "syn",
+ "wasm-metadata",
+ "wit-bindgen-core",
+ "wit-component",
+]
+
+[[package]]
+name = "wit-bindgen-rust-macro"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c0f9bfd77e6a48eccf51359e3ae77140a7f50b1e2ebfe62422d8afdaffab17a"
+dependencies = [
+ "anyhow",
+ "prettyplease",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wit-bindgen-core",
+ "wit-bindgen-rust",
+]
+
+[[package]]
+name = "wit-component"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
+dependencies = [
+ "anyhow",
+ "bitflags",
+ "indexmap",
+ "log",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "wasm-encoder",
+ "wasm-metadata",
+ "wasmparser",
+ "wit-parser",
+]
+
+[[package]]
+name = "wit-parser"
+version = "0.244.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736"
+dependencies = [
+ "anyhow",
+ "id-arena",
+ "indexmap",
+ "log",
+ "semver",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "unicode-xid",
+ "wasmparser",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
diff --git a/tools/kapi/Cargo.toml b/tools/kapi/Cargo.toml
new file mode 100644
index 0000000000000..159e65d324468
--- /dev/null
+++ b/tools/kapi/Cargo.toml
@@ -0,0 +1,20 @@
+[package]
+name = "kapi"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.85"
+authors = ["Sasha Levin <sashal@kernel.org>"]
+description = "Tool for extracting and displaying kernel API specifications"
+license = "GPL-2.0"
+
+[dependencies]
+goblin = "0.10"
+clap = { version = "4.4", features = ["derive"] }
+anyhow = "1.0"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+regex = "1.10"
+walkdir = "2.4"
+
+[dev-dependencies]
+tempfile = "3.8"
diff --git a/tools/kapi/Makefile b/tools/kapi/Makefile
new file mode 100644
index 0000000000000..d4234538e4eee
--- /dev/null
+++ b/tools/kapi/Makefile
@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: GPL-2.0
+# Makefile wrapper for the kapi tool (Rust userspace binary).
+#
+# See Documentation/dev-tools/kernel-api-spec.rst for details.
+
+PREFIX ?= /usr/local
+
+.PHONY: all build release debug clean install test fmt clippy
+
+all: release
+
+release:
+ cargo build --release
+
+build: release
+
+debug:
+ cargo build
+
+test:
+ cargo test
+
+fmt:
+ cargo fmt --all -- --check
+
+clippy:
+ cargo clippy --all-targets --all-features -- -D warnings
+
+clean:
+ cargo clean
+
+install: release
+ install -D -m 0755 target/release/kapi $(DESTDIR)$(PREFIX)/bin/kapi
diff --git a/tools/kapi/README.md b/tools/kapi/README.md
new file mode 100644
index 0000000000000..3839f3ff2964a
--- /dev/null
+++ b/tools/kapi/README.md
@@ -0,0 +1,33 @@
+# kapi — Kernel API Specification Extractor
+
+Userspace utility that extracts and displays kernel API specifications from
+three sources:
+
+- `--source PATH` — parse kerneldoc blocks in a C source file or tree
+- `--vmlinux PATH` — decode the `.kapi_specs` ELF section of a compiled vmlinux
+- `--debugfs PATH` — read the live specs from `/sys/kernel/debug/kapi/` on a
+ running kernel (this is also the mode used when no input option is given, in
+ which case PATH is `/sys/kernel/debug`)
+
+Output formats: `plain` (default), `json`, `rst`.
+
+See `Documentation/dev-tools/kernel-api-spec.rst` for the full user guide,
+including the kerneldoc DSL reference and the surrounding framework design.
+
+## Build
+
+```
+make -C tools/kapi
+```
+
+(wraps `cargo build --release`; the binary is produced at
+`tools/kapi/target/release/kapi`).
+
+## Usage
+
+```
+tools/kapi/target/release/kapi --help
+tools/kapi/target/release/kapi --source fs/open.c sys_open
+tools/kapi/target/release/kapi --vmlinux vmlinux -f json
+tools/kapi/target/release/kapi --debugfs /sys/kernel/debug
+```
--git a/tools/kapi/src/extractor/debugfs.rs b/tools/kapi/src/extractor/debugfs.rs
new file mode 100644
index 0000000000000..0a7e41e1c40ca
--- /dev/null
+++ b/tools/kapi/src/extractor/debugfs.rs
@@ -0,0 +1,1704 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+use crate::formatter::OutputFormatter;
+use anyhow::{bail, Context, Result};
+use serde::Deserialize;
+use std::fs;
+use std::io::Write;
+use std::path::PathBuf;
+
+use super::{
+ display_api_spec, ApiExtractor, ApiSpec, CapabilitySpec, ConstraintSpec, ErrorSpec, LockSpec,
+ ParamSpec, ReturnSpec, SignalMaskSpec, StateTransitionSpec, StructFieldSpec, StructSpec,
+};
+
+// Schema matching what kapi_export_json() in the kernel emits. The kernel
+// serialises several enum-like fields as hex strings ("0x%x") or token
+// strings ("exact", "process"); we keep them as Option<String> here and
+// interpret them during conversion.
+#[derive(Deserialize)]
+struct KernelApiJson {
+ name: String,
+ #[serde(default)]
+ api_type: Option<String>,
+ #[serde(default)]
+ version: Option<u32>,
+ #[serde(default)]
+ description: Option<String>,
+ #[serde(default)]
+ long_description: Option<String>,
+ #[serde(default)]
+ context_flags: Option<String>,
+ #[serde(default)]
+ examples: Option<String>,
+ #[serde(default)]
+ notes: Option<String>,
+ #[serde(default)]
+ capabilities: Option<Vec<KernelCapabilityJson>>,
+ #[serde(default)]
+ parameters: Option<Vec<KernelParamJson>>,
+ #[serde(default)]
+ errors: Option<Vec<KernelErrorJson>>,
+ #[serde(default, rename = "return")]
+ return_spec: Option<KernelReturnJson>,
+ #[serde(default)]
+ locks: Option<Vec<KernelLockJson>>,
+ #[serde(default)]
+ constraints: Option<Vec<KernelConstraintJson>>,
+ #[serde(default)]
+ signals: Option<Vec<KernelSignalJson>>,
+ #[serde(default)]
+ side_effects: Option<Vec<KernelSideEffectJson>>,
+ #[serde(default)]
+ state_transitions: Option<Vec<KernelStateTransitionJson>>,
+ #[serde(default)]
+ signal_masks: Option<Vec<KernelSignalMaskJson>>,
+ #[serde(default)]
+ struct_specs: Option<Vec<KernelStructJson>>,
+}
+
+#[derive(Deserialize)]
+struct KernelStateTransitionJson {
+ #[serde(default)]
+ object: Option<String>,
+ #[serde(default)]
+ from_state: Option<String>,
+ #[serde(default)]
+ to_state: Option<String>,
+ #[serde(default)]
+ condition: Option<String>,
+ #[serde(default)]
+ description: Option<String>,
+}
+
+#[derive(Deserialize)]
+struct KernelSignalMaskJson {
+ #[serde(default)]
+ name: Option<String>,
+ #[serde(default)]
+ description: Option<String>,
+ #[serde(default)]
+ signals: Vec<i32>,
+}
+
+#[derive(Deserialize)]
+struct KernelStructFieldJson {
+ #[serde(default)]
+ name: Option<String>,
+ #[serde(rename = "type", default)]
+ type_name: Option<String>,
+ #[serde(default)]
+ type_class: Option<String>,
+ #[serde(default)]
+ offset: usize,
+ #[serde(default)]
+ size: usize,
+ #[serde(default)]
+ flags: Option<String>,
+ #[serde(default)]
+ constraint_type: Option<String>,
+ #[serde(default)]
+ min_value: i64,
+ #[serde(default)]
+ max_value: i64,
+ #[serde(default)]
+ valid_mask: Option<String>,
+ #[serde(default)]
+ description: Option<String>,
+}
+
+#[derive(Deserialize)]
+struct KernelStructJson {
+ #[serde(default)]
+ name: Option<String>,
+ #[serde(default)]
+ size: usize,
+ #[serde(default)]
+ alignment: usize,
+ #[serde(default)]
+ description: Option<String>,
+ #[serde(default)]
+ fields: Vec<KernelStructFieldJson>,
+}
+
+#[derive(Deserialize)]
+struct KernelConstraintJson {
+ name: String,
+ #[serde(default)]
+ description: Option<String>,
+ #[serde(default)]
+ expression: Option<String>,
+}
+
+#[derive(Deserialize)]
+struct KernelSignalJson {
+ #[serde(default)]
+ signal_num: i32,
+ #[serde(default)]
+ signal_name: Option<String>,
+ #[serde(default)]
+ direction: Option<String>,
+ #[serde(default)]
+ action: u32,
+ #[serde(default)]
+ target: Option<String>,
+ #[serde(default)]
+ condition: Option<String>,
+ #[serde(default)]
+ description: Option<String>,
+ #[serde(default)]
+ restartable: bool,
+ #[serde(default)]
+ sa_flags_required: Option<String>,
+ #[serde(default)]
+ sa_flags_forbidden: Option<String>,
+ #[serde(default)]
+ error_on_signal: i32,
+ #[serde(default)]
+ transform_to: i32,
+ #[serde(default)]
+ timing: Option<String>,
+ #[serde(default)]
+ priority: u32,
+ #[serde(default)]
+ interruptible: bool,
+ #[serde(default)]
+ queue_behavior: Option<String>,
+ #[serde(default)]
+ state_required: Option<String>,
+ #[serde(default)]
+ state_forbidden: Option<String>,
+}
+
+#[derive(Deserialize)]
+struct KernelSideEffectJson {
+ #[serde(rename = "type", default)]
+ type_hex: Option<String>,
+ #[serde(default)]
+ target: Option<String>,
+ #[serde(default)]
+ condition: Option<String>,
+ #[serde(default)]
+ description: Option<String>,
+ #[serde(default)]
+ reversible: bool,
+}
+
+#[derive(Deserialize)]
+struct KernelParamJson {
+ name: String,
+ #[serde(rename = "type", default)]
+ type_name: Option<String>,
+ #[serde(default)]
+ type_class: Option<String>,
+ #[serde(default)]
+ description: Option<String>,
+ #[serde(default)]
+ flags: Option<String>,
+ #[serde(default)]
+ constraint_type: Option<String>,
+ #[serde(default)]
+ constraint_desc: Option<String>,
+ #[serde(default)]
+ min_value: Option<i64>,
+ #[serde(default)]
+ max_value: Option<i64>,
+ #[serde(default)]
+ valid_mask: Option<String>,
+ #[serde(default)]
+ enum_values: Vec<i64>,
+ #[serde(default)]
+ size: Option<u64>,
+ #[serde(default)]
+ alignment: Option<u64>,
+ #[serde(default)]
+ size_param_idx: Option<u32>,
+}
+
+#[derive(Deserialize)]
+struct KernelErrorJson {
+ #[serde(rename = "code")]
+ error_code: i32,
+ #[serde(default)]
+ name: Option<String>,
+ #[serde(default)]
+ condition: Option<String>,
+ #[serde(default)]
+ description: Option<String>,
+}
+
+#[derive(Deserialize)]
+struct KernelReturnJson {
+ #[serde(rename = "type", default)]
+ type_name: Option<String>,
+ #[serde(default)]
+ type_class: Option<String>,
+ #[serde(default)]
+ check_type: Option<String>,
+ #[serde(default)]
+ description: Option<String>,
+ #[serde(default)]
+ success_value: Option<i64>,
+ #[serde(default)]
+ success_min: Option<i64>,
+ #[serde(default)]
+ success_max: Option<i64>,
+ #[serde(default)]
+ error_values: Vec<i64>,
+}
+
+#[derive(Deserialize)]
+struct KernelLockJson {
+ name: String,
+ #[serde(rename = "type", default)]
+ lock_type: Option<String>,
+ #[serde(default)]
+ scope: Option<String>,
+ #[serde(default)]
+ description: Option<String>,
+}
+
+#[derive(Deserialize)]
+struct KernelCapabilityJson {
+ capability: i32,
+ name: String,
+ action: String,
+ allows: String,
+ without_cap: String,
+ check_condition: Option<String>,
+ priority: Option<u8>,
+ alternatives: Option<Vec<i32>>,
+}
+
+/// Free-text fields of the text dump that may span several lines.
+#[derive(Clone, Copy)]
+enum TextField {
+ Description,
+ LongDescription,
+ Examples,
+ Notes,
+}
+
+impl TextField {
+ /// Recognise the header line of a text field, returning the field and
+ /// whatever follows the colon on the same line.
+ fn start(line: &str) -> Option<(Self, &str)> {
+ [
+ ("Description:", Self::Description),
+ ("Long description:", Self::LongDescription),
+ ("Examples:", Self::Examples),
+ ("Notes:", Self::Notes),
+ ]
+ .into_iter()
+ .find_map(|(header, field)| {
+ line.strip_prefix(header)
+ .map(|rest| (field, rest.trim_start()))
+ })
+ }
+
+ fn store(self, spec: &mut ApiSpec, lines: &[String]) {
+ let text = lines.join("\n");
+ let text = text.trim_matches('\n').trim_end().to_string();
+ let slot = match self {
+ Self::Description => &mut spec.description,
+ Self::LongDescription => &mut spec.long_description,
+ Self::Examples => &mut spec.examples,
+ Self::Notes => &mut spec.notes,
+ };
+ *slot = Some(text);
+ }
+}
+
+/// Extractor for kernel API specifications from debugfs
+pub struct DebugfsExtractor {
+ debugfs_path: PathBuf,
+}
+
+impl DebugfsExtractor {
+ /// Create a new debugfs extractor with the specified debugfs path
+ pub fn new(debugfs_path: Option<String>) -> Result<Self> {
+ let path = match debugfs_path {
+ Some(p) => PathBuf::from(p),
+ None => PathBuf::from("/sys/kernel/debug"),
+ };
+
+ // Check if the debugfs path exists
+ if !path.exists() {
+ bail!("Debugfs path does not exist: {}", path.display());
+ }
+
+ // Check if kapi directory exists
+ let kapi_path = path.join("kapi");
+ if !kapi_path.exists() {
+ bail!(
+ "Kernel API debugfs interface not found at: {}",
+ kapi_path.display()
+ );
+ }
+
+ Ok(Self { debugfs_path: path })
+ }
+
+ /// Parse the list file to get all available API names
+ fn parse_list_file(&self) -> Result<Vec<String>> {
+ let list_path = self.debugfs_path.join("kapi/list");
+ let content = fs::read_to_string(&list_path)
+ .with_context(|| format!("Failed to read {}", list_path.display()))?;
+
+ let mut apis = Vec::new();
+ let mut in_list = false;
+
+ for line in content.lines() {
+ if line.contains("===") {
+ in_list = true;
+ continue;
+ }
+
+ if in_list && line.starts_with("Total:") {
+ break;
+ }
+
+ if in_list && !line.trim().is_empty() {
+ // Extract API name from lines like "sys_read - Read from a file descriptor"
+ if let Some(name) = line.split(" - ").next() {
+ apis.push(name.trim().to_string());
+ }
+ }
+ }
+
+ Ok(apis)
+ }
+
+ /// Convert context flags (emitted by the kernel as a hex string like
+ /// "0x21") into the token list consumed by the formatter.
+ fn parse_context_flags(flags: &str) -> Vec<String> {
+ let mut result = Vec::new();
+ let bits = flags
+ .strip_prefix("0x")
+ .or_else(|| flags.strip_prefix("0X"))
+ .unwrap_or(flags);
+ let Ok(flags) = u32::from_str_radix(bits, 16) else {
+ return result;
+ };
+
+ // These values should match KAPI_CTX_* flags from kernel
+ if flags & (1 << 0) != 0 {
+ result.push("KAPI_CTX_PROCESS".to_string());
+ }
+ if flags & (1 << 1) != 0 {
+ result.push("KAPI_CTX_SOFTIRQ".to_string());
+ }
+ if flags & (1 << 2) != 0 {
+ result.push("KAPI_CTX_HARDIRQ".to_string());
+ }
+ if flags & (1 << 3) != 0 {
+ result.push("KAPI_CTX_NMI".to_string());
+ }
+ if flags & (1 << 4) != 0 {
+ result.push("KAPI_CTX_ATOMIC".to_string());
+ }
+ if flags & (1 << 5) != 0 {
+ result.push("KAPI_CTX_SLEEPABLE".to_string());
+ }
+ if flags & (1 << 6) != 0 {
+ result.push("KAPI_CTX_PREEMPT_DISABLED".to_string());
+ }
+ if flags & (1 << 7) != 0 {
+ result.push("KAPI_CTX_IRQ_DISABLED".to_string());
+ }
+
+ result
+ }
+
+ /// Parse a hex-string like "0x123" into u64, returning 0 on failure.
+ fn parse_hex_u64(value: &str) -> u64 {
+ let bits = value
+ .strip_prefix("0x")
+ .or_else(|| value.strip_prefix("0X"))
+ .unwrap_or(value);
+ u64::from_str_radix(bits, 16).unwrap_or(0)
+ }
+
+ /// Parse a hex-string like "0x123" into u32, returning 0 on failure.
+ fn parse_hex_u32(value: &str) -> u32 {
+ u32::try_from(Self::parse_hex_u64(value)).unwrap_or(0)
+ }
+
+ /// Map the type-class token emitted by the kernel (param_type_to_string)
+ /// back to the numeric enum kapi_param_type.
+ fn parse_type_class(token: &str) -> u32 {
+ match token {
+ "void" => 0,
+ "int" => 1,
+ "uint" => 2,
+ "pointer" => 3,
+ "struct" => 4,
+ "union" => 5,
+ "enum" => 6,
+ "function_pointer" => 7,
+ "array" => 8,
+ "file_descriptor" => 9,
+ "user_pointer" => 10,
+ "pathname" => 11,
+ "custom" => 12,
+ _ => 0,
+ }
+ }
+
+ /// Map the constraint-type token emitted by the kernel
+ /// (constraint_type_to_string) back to the numeric enum
+ /// kapi_constraint_type.
+ fn parse_constraint_type(token: &str) -> u32 {
+ match token {
+ "none" => 0,
+ "range" => 1,
+ "mask" => 2,
+ "enum" => 3,
+ "alignment" => 4,
+ "power_of_two" => 5,
+ "page_aligned" => 6,
+ "nonzero" => 7,
+ "user_string" => 8,
+ "user_path" => 9,
+ "user_ptr" => 10,
+ "buffer" => 11,
+ "custom" => 12,
+ _ => 0,
+ }
+ }
+
+ /// Derive the API type from the symbol name, the same way the vmlinux
+ /// extractor does.
+ fn api_type_from_name(name: &str) -> &'static str {
+ if name.starts_with("sys_") {
+ "syscall"
+ } else if name.ends_with("_ioctl") {
+ "ioctl"
+ } else if name.contains("sysfs") {
+ "sysfs"
+ } else {
+ "function"
+ }
+ }
+
+ /// Map the check-type token emitted by the kernel
+ /// (return_check_type_to_string) back to the u32 enum the formatter wants.
+ fn parse_check_type(token: &str) -> u32 {
+ match token {
+ "exact" => 0,
+ "range" => 1,
+ "error_check" => 2,
+ "file_descriptor" => 3,
+ "custom" => 4,
+ "no_return" => 5,
+ _ => 0,
+ }
+ }
+
+ /// Map the lock-type token emitted by the kernel (lock_type_to_string).
+ fn parse_lock_type(token: &str) -> u32 {
+ match token {
+ "none" => 0,
+ "mutex" => 1,
+ "spinlock" => 2,
+ "rwlock" => 3,
+ "seqlock" => 4,
+ "rcu" => 5,
+ "semaphore" => 6,
+ "custom" => 7,
+ _ => 0,
+ }
+ }
+
+ /// Map the lock-scope token emitted by the kernel (lock_scope_to_string).
+ fn parse_lock_scope(token: &str) -> u32 {
+ match token {
+ "internal" => 0,
+ "acquires" => 1,
+ "releases" => 2,
+ "caller_held" => 3,
+ _ => 0,
+ }
+ }
+
+ /// Map the signal-timing token (e.g. "during") back to the u32 enum that
+ /// the source-side parser produces. Mirrors
+ /// KerneldocParser::parse_signal_timing in kerneldoc_parser.rs so the
+ /// debugfs path and the source path agree.
+ fn parse_signal_timing(token: &str) -> u32 {
+ match token.trim().to_ascii_lowercase().as_str() {
+ "before" => 0,
+ "during" => 1,
+ "after" => 2,
+ _ => 0,
+ }
+ }
+
+ /// Convert the capability action token emitted by the kernel
+ /// (capability_action_to_string) to the KAPI_CAP_* spelling used by the
+ /// other extractors.
+ fn parse_capability_action(action: &str) -> String {
+ match action {
+ "bypass_check" => "KAPI_CAP_BYPASS_CHECK".to_string(),
+ "increase_limit" => "KAPI_CAP_INCREASE_LIMIT".to_string(),
+ "override_restriction" => "KAPI_CAP_OVERRIDE_RESTRICTION".to_string(),
+ "grant_permission" => "KAPI_CAP_GRANT_PERMISSION".to_string(),
+ "modify_behavior" => "KAPI_CAP_MODIFY_BEHAVIOR".to_string(),
+ "access_resource" => "KAPI_CAP_ACCESS_RESOURCE".to_string(),
+ "perform_operation" => "KAPI_CAP_PERFORM_OPERATION".to_string(),
+ _ => action.to_string(),
+ }
+ }
+
+ /// Try to parse as JSON first
+ fn try_parse_json(&self, content: &str) -> Result<ApiSpec, serde_json::Error> {
+ let json_data: KernelApiJson = serde_json::from_str(content)?;
+ // The kernel-side kapi_json_str() emits NULL char * as the empty
+ // string "", so normalise empty -> None to match the ApiSpec
+ // convention used by --source / --vmlinux.
+ fn opt_str(s: Option<String>) -> Option<String> {
+ s.filter(|v| !v.is_empty())
+ }
+ let api_type = json_data
+ .api_type
+ .unwrap_or_else(|| Self::api_type_from_name(&json_data.name).to_string());
+
+ let mut spec = ApiSpec {
+ name: json_data.name,
+ api_type,
+ description: opt_str(json_data.description),
+ long_description: opt_str(json_data.long_description),
+ version: json_data.version.map(|v| v.to_string()),
+ context_flags: json_data
+ .context_flags
+ .as_deref()
+ .map_or_else(Vec::new, Self::parse_context_flags),
+ param_count: None,
+ error_count: None,
+ examples: opt_str(json_data.examples),
+ notes: opt_str(json_data.notes),
+ subsystem: None, // Not in the JSON format
+ sysfs_path: None, // Not in the JSON format
+ permissions: None, // Not in the JSON format
+ capabilities: vec![],
+ parameters: vec![],
+ return_spec: None,
+ errors: vec![],
+ signals: vec![],
+ signal_masks: vec![],
+ side_effects: vec![],
+ state_transitions: vec![],
+ constraints: vec![],
+ locks: vec![],
+ struct_specs: vec![],
+ };
+
+ // Convert capabilities
+ if let Some(caps) = json_data.capabilities {
+ for cap in caps {
+ spec.capabilities.push(CapabilitySpec {
+ capability: cap.capability,
+ name: cap.name,
+ action: Self::parse_capability_action(&cap.action),
+ allows: cap.allows,
+ without_cap: cap.without_cap,
+ check_condition: opt_str(cap.check_condition),
+ priority: cap.priority,
+ alternatives: cap.alternatives.unwrap_or_default(),
+ });
+ }
+ }
+
+ // Convert parameters.
+ if let Some(params) = json_data.parameters {
+ for (i, p) in params.into_iter().enumerate() {
+ let flags = p.flags.as_deref().map_or(0, Self::parse_hex_u32);
+ let mut param = ParamSpec {
+ index: i as u32,
+ name: p.name,
+ type_name: p.type_name.unwrap_or_default(),
+ description: p.description.unwrap_or_default(),
+ flags,
+ param_type: p.type_class.as_deref().map_or(0, Self::parse_type_class),
+ constraint_type: p
+ .constraint_type
+ .as_deref()
+ .map_or(0, Self::parse_constraint_type),
+ constraint: opt_str(p.constraint_desc),
+ min_value: p.min_value,
+ max_value: p.max_value,
+ valid_mask: p.valid_mask.as_deref().map(Self::parse_hex_u64),
+ enum_values: p.enum_values.iter().map(i64::to_string).collect(),
+ size: p.size.map(|v| v as u32),
+ alignment: p.alignment.map(|v| v as u32),
+ size_param_idx: p.size_param_idx,
+ };
+ param.keep_used_numbers();
+ spec.parameters.push(param);
+ }
+ if !spec.parameters.is_empty() {
+ spec.param_count = Some(spec.parameters.len() as u32);
+ }
+ }
+
+ // Convert errors
+ if let Some(errors) = json_data.errors {
+ for e in errors {
+ spec.errors.push(ErrorSpec {
+ error_code: e.error_code,
+ name: e.name.unwrap_or_default(),
+ condition: e.condition.unwrap_or_default(),
+ description: e.description.unwrap_or_default(),
+ });
+ }
+ if !spec.errors.is_empty() {
+ spec.error_count = Some(spec.errors.len() as u32);
+ }
+ }
+
+ // Convert return spec
+ if let Some(ret) = json_data.return_spec {
+ let check_type = ret.check_type.as_deref().map_or(0, Self::parse_check_type);
+ let return_type = ret.type_class.as_deref().map_or(0, Self::parse_type_class);
+ let type_name = ret.type_name.unwrap_or_default();
+ let success_value = ret.success_value.unwrap_or(0);
+ // A spec without a return block exports as an all-zero return
+ // spec; report it as absent like the vmlinux extractor does.
+ if !(type_name.is_empty() && return_type == 0 && check_type == 0 && success_value == 0)
+ {
+ let mut ret_spec = ReturnSpec {
+ type_name,
+ description: ret.description.unwrap_or_default(),
+ return_type,
+ check_type,
+ success_value: ret.success_value,
+ success_min: ret.success_min,
+ success_max: ret.success_max,
+ error_values: ret
+ .error_values
+ .into_iter()
+ .filter_map(|v| i32::try_from(v).ok())
+ .collect(),
+ };
+ ret_spec.keep_used_success_fields();
+ spec.return_spec = Some(ret_spec);
+ }
+ }
+
+ // Convert locks
+ if let Some(locks) = json_data.locks {
+ for l in locks {
+ let lock_type = l.lock_type.as_deref().map_or(0, Self::parse_lock_type);
+ let scope = l.scope.as_deref().map_or(0, Self::parse_lock_scope);
+ spec.locks.push(LockSpec {
+ lock_name: l.name,
+ lock_type,
+ scope,
+ description: l.description.unwrap_or_default(),
+ });
+ }
+ }
+
+ // Convert constraints. Empty strings emitted from kapi_json_str()
+ // for NULL char * fields normalise back to None to match --source.
+ if let Some(constraints) = json_data.constraints {
+ for c in constraints {
+ spec.constraints.push(ConstraintSpec {
+ name: c.name,
+ description: c.description.unwrap_or_default(),
+ expression: c.expression.filter(|v| !v.is_empty()),
+ });
+ }
+ }
+
+ // Convert signals.
+ if let Some(signals) = json_data.signals {
+ for s in signals {
+ let direction = s.direction.as_deref().map_or(0, Self::parse_hex_u32);
+ let sa_flags_required = s
+ .sa_flags_required
+ .as_deref()
+ .map_or(0, Self::parse_hex_u32);
+ let sa_flags_forbidden = s
+ .sa_flags_forbidden
+ .as_deref()
+ .map_or(0, Self::parse_hex_u32);
+ let state_required = s.state_required.as_deref().map_or(0, Self::parse_hex_u32);
+ let state_forbidden = s.state_forbidden.as_deref().map_or(0, Self::parse_hex_u32);
+ let timing = s.timing.as_deref().map_or(0, Self::parse_signal_timing);
+ spec.signals.push(super::SignalSpec {
+ signal_num: s.signal_num,
+ signal_name: s.signal_name.unwrap_or_default(),
+ direction,
+ action: s.action,
+ target: opt_str(s.target),
+ condition: opt_str(s.condition),
+ description: opt_str(s.description),
+ timing,
+ priority: s.priority,
+ restartable: s.restartable,
+ interruptible: s.interruptible,
+ queue: opt_str(s.queue_behavior),
+ sa_flags: 0,
+ sa_flags_required,
+ sa_flags_forbidden,
+ state_required,
+ state_forbidden,
+ error_on_signal: if s.error_on_signal != 0 {
+ Some(s.error_on_signal)
+ } else {
+ None
+ },
+ transform_to: if s.transform_to != 0 {
+ // Kernel JSON already carries the numeric value.
+ Some(s.transform_to)
+ } else {
+ None
+ },
+ });
+ }
+ }
+
+ // Convert side effects.
+ if let Some(effects) = json_data.side_effects {
+ for e in effects {
+ let effect_type = e.type_hex.as_deref().map_or(0, Self::parse_hex_u32);
+ spec.side_effects.push(super::SideEffectSpec {
+ effect_type,
+ target: e.target.unwrap_or_default(),
+ condition: e.condition.filter(|v| !v.is_empty()),
+ description: e.description.unwrap_or_default(),
+ reversible: e.reversible,
+ });
+ }
+ }
+
+ if let Some(transitions) = json_data.state_transitions {
+ for t in transitions {
+ spec.state_transitions.push(StateTransitionSpec {
+ object: t.object.unwrap_or_default(),
+ from_state: t.from_state.unwrap_or_default(),
+ to_state: t.to_state.unwrap_or_default(),
+ condition: opt_str(t.condition),
+ description: t.description.unwrap_or_default(),
+ });
+ }
+ }
+
+ if let Some(masks) = json_data.signal_masks {
+ for m in masks {
+ spec.signal_masks.push(SignalMaskSpec {
+ name: m.name.unwrap_or_default(),
+ description: m.description.unwrap_or_default(),
+ signals: m.signals,
+ });
+ }
+ }
+
+ if let Some(structs) = json_data.struct_specs {
+ for st in structs {
+ let fields: Vec<StructFieldSpec> = st
+ .fields
+ .into_iter()
+ .map(|f| StructFieldSpec {
+ name: f.name.unwrap_or_default(),
+ field_type: f.type_class.as_deref().map_or(0, Self::parse_type_class),
+ type_name: f.type_name.unwrap_or_default(),
+ offset: f.offset,
+ size: f.size,
+ flags: f.flags.as_deref().map_or(0, Self::parse_hex_u32),
+ constraint_type: f
+ .constraint_type
+ .as_deref()
+ .map_or(0, Self::parse_constraint_type),
+ min_value: f.min_value,
+ max_value: f.max_value,
+ valid_mask: f.valid_mask.as_deref().map_or(0, Self::parse_hex_u64),
+ description: f.description.unwrap_or_default(),
+ })
+ .collect();
+ spec.struct_specs.push(StructSpec {
+ name: st.name.unwrap_or_default(),
+ size: st.size,
+ alignment: st.alignment,
+ field_count: fields.len() as u32,
+ fields,
+ description: st.description.unwrap_or_default(),
+ });
+ }
+ }
+
+ Ok(spec)
+ }
+
+ /// Parse a single API specification file
+ fn parse_spec_file(&self, api_name: &str) -> Result<ApiSpec> {
+ // Prefer the JSON endpoint; fall back to the plain-text dump under
+ // kapi/specs/ if it is missing or does not parse.
+ let json_path = self
+ .debugfs_path
+ .join(format!("kapi/specs-json/{}", api_name));
+ match fs::read_to_string(&json_path) {
+ Ok(content) => match self.try_parse_json(&content) {
+ Ok(spec) => return Ok(spec),
+ Err(e) => eprintln!(
+ "Warning: invalid JSON in {}: {}; using the text dump",
+ json_path.display(),
+ e
+ ),
+ },
+ Err(e) if e.kind() != std::io::ErrorKind::NotFound => eprintln!(
+ "Warning: cannot read {}: {}; using the text dump",
+ json_path.display(),
+ e
+ ),
+ Err(_) => {}
+ }
+
+ let spec_path = self.debugfs_path.join(format!("kapi/specs/{}", api_name));
+ let content = fs::read_to_string(&spec_path)
+ .with_context(|| format!("Failed to read {}", spec_path.display()))?;
+
+ // The specs/ file may hold JSON as well.
+ if let Ok(spec) = self.try_parse_json(&content) {
+ return Ok(spec);
+ }
+
+ // Fall back to plain text parsing
+ let mut spec = ApiSpec {
+ name: api_name.to_string(),
+ api_type: "unknown".to_string(),
+ description: None,
+ long_description: None,
+ version: None,
+ context_flags: Vec::new(),
+ param_count: None,
+ error_count: None,
+ examples: None,
+ notes: None,
+ subsystem: None,
+ sysfs_path: None,
+ permissions: None,
+ capabilities: vec![],
+ parameters: vec![],
+ return_spec: None,
+ errors: vec![],
+ signals: vec![],
+ signal_masks: vec![],
+ side_effects: vec![],
+ state_transitions: vec![],
+ constraints: vec![],
+ locks: vec![],
+ struct_specs: vec![],
+ };
+
+ // Parse the content
+ let mut text_field: Option<TextField> = None;
+ let mut text_lines: Vec<String> = Vec::new();
+ let mut parsing_capability = false;
+ let mut in_capabilities_section = false;
+ let mut current_capability: Option<CapabilitySpec> = None;
+
+ for line in content.lines() {
+ // The kernel indents every line of a multi-line value, so a value
+ // ends at the first non-blank line that is not indented.
+ if let Some(field) = text_field {
+ if line.is_empty() {
+ text_lines.push(String::new());
+ continue;
+ }
+ if let Some(rest) = line.strip_prefix(" ") {
+ text_lines.push(rest.to_string());
+ continue;
+ }
+ field.store(&mut spec, &text_lines);
+ text_field = None;
+ }
+
+ // Handle capability sections
+ if line.starts_with("Capabilities (") {
+ in_capabilities_section = true;
+ continue;
+ }
+ // Any other top-level section header ends the capabilities section
+ // so that " pending_signals (0):" inside "Signal handling (1):"
+ // isn't mis-parsed as a capability entry.
+ if !line.starts_with(' ') && !line.is_empty() && line.ends_with(':') {
+ in_capabilities_section = false;
+ }
+ if in_capabilities_section
+ && line.starts_with(" ")
+ && line.contains(" (")
+ && line.ends_with("):")
+ {
+ // Start of a capability entry like " CAP_IPC_LOCK (14):"
+ if let Some(cap) = current_capability.take() {
+ spec.capabilities.push(cap);
+ }
+
+ let parts: Vec<&str> = line.trim().split(" (").collect();
+ if parts.len() == 2 {
+ let cap_name = parts[0].to_string();
+ let cap_id = parts[1].trim_end_matches("):").parse().unwrap_or(0);
+ current_capability = Some(CapabilitySpec {
+ capability: cap_id,
+ name: cap_name,
+ action: String::new(),
+ allows: String::new(),
+ without_cap: String::new(),
+ check_condition: None,
+ priority: None,
+ alternatives: Vec::new(),
+ });
+ parsing_capability = true;
+ }
+ continue;
+ }
+ if parsing_capability && line.starts_with(" ") {
+ // Parse capability fields
+ if let Some(ref mut cap) = current_capability {
+ if let Some(action) = line.strip_prefix(" Action: ") {
+ cap.action = action.to_string();
+ } else if let Some(allows) = line.strip_prefix(" Allows: ") {
+ cap.allows = allows.to_string();
+ } else if let Some(without) = line.strip_prefix(" Without: ") {
+ cap.without_cap = without.to_string();
+ } else if let Some(cond) = line.strip_prefix(" Condition: ") {
+ cap.check_condition = Some(cond.to_string());
+ } else if let Some(prio) = line.strip_prefix(" Priority: ") {
+ cap.priority = prio.parse().ok();
+ } else if let Some(alts) = line.strip_prefix(" Alternatives: ") {
+ cap.alternatives =
+ alts.split(", ").filter_map(|s| s.parse().ok()).collect();
+ }
+ }
+ continue;
+ }
+ if parsing_capability && !line.starts_with(" ") {
+ // End of capabilities section
+ if let Some(cap) = current_capability.take() {
+ spec.capabilities.push(cap);
+ }
+ parsing_capability = false;
+ }
+
+ // Handle section headers
+ if line.starts_with("Parameters (") {
+ if let Some(count_str) = line
+ .strip_prefix("Parameters (")
+ .and_then(|s| s.strip_suffix("):"))
+ {
+ spec.param_count = count_str.parse().ok();
+ }
+ continue;
+ } else if line.starts_with("Errors (") {
+ if let Some(count_str) = line
+ .strip_prefix("Errors (")
+ .and_then(|s| s.strip_suffix("):"))
+ {
+ spec.error_count = count_str.parse().ok();
+ }
+ continue;
+ }
+
+ // Parse regular fields
+ if let Some((field, first)) = TextField::start(line) {
+ text_field = Some(field);
+ text_lines.clear();
+ if !first.is_empty() {
+ text_lines.push(first.to_string());
+ }
+ } else if let Some(version) = line.strip_prefix("Version: ") {
+ spec.version = Some(version.to_string());
+ } else if let Some(flags) = line.strip_prefix("Context flags: ") {
+ spec.context_flags = flags
+ .split_whitespace()
+ .map(|f| format!("KAPI_CTX_{f}"))
+ .collect();
+ } else if let Some(subsys) = line.strip_prefix("Subsystem: ") {
+ spec.subsystem = Some(subsys.to_string());
+ } else if let Some(path) = line.strip_prefix("Sysfs Path: ") {
+ spec.sysfs_path = Some(path.to_string());
+ } else if let Some(perms) = line.strip_prefix("Permissions: ") {
+ spec.permissions = Some(perms.to_string());
+ }
+ }
+
+ if let Some(field) = text_field {
+ field.store(&mut spec, &text_lines);
+ }
+
+ // Handle any remaining capability
+ if let Some(cap) = current_capability.take() {
+ spec.capabilities.push(cap);
+ }
+
+ // Determine API type based on name
+ if api_name.starts_with("sys_") {
+ spec.api_type = "syscall".to_string();
+ } else if api_name.contains("_ioctl") || api_name.starts_with("ioctl_") {
+ spec.api_type = "ioctl".to_string();
+ } else if api_name.contains("sysfs")
+ || api_name.ends_with("_show")
+ || api_name.ends_with("_store")
+ {
+ spec.api_type = "sysfs".to_string();
+ } else {
+ spec.api_type = "function".to_string();
+ }
+
+ Ok(spec)
+ }
+}
+
+impl ApiExtractor for DebugfsExtractor {
+ fn extract_all(&self) -> Result<Vec<ApiSpec>> {
+ let api_names = self.parse_list_file()?;
+ let mut specs = Vec::new();
+
+ for name in api_names {
+ match self.parse_spec_file(&name) {
+ Ok(spec) => specs.push(spec),
+ Err(e) => {
+ eprintln!("Warning: failed to parse API spec '{}': {}", name, e);
+ }
+ }
+ }
+
+ Ok(specs)
+ }
+
+ fn extract_by_name(&self, name: &str) -> Result<Option<ApiSpec>> {
+ let api_names = self.parse_list_file()?;
+
+ if api_names.contains(&name.to_string()) {
+ Ok(Some(self.parse_spec_file(name)?))
+ } else {
+ Ok(None)
+ }
+ }
+
+ fn display_api_details(
+ &self,
+ api_name: &str,
+ formatter: &mut dyn OutputFormatter,
+ writer: &mut dyn Write,
+ ) -> Result<()> {
+ if let Some(spec) = self.extract_by_name(api_name)? {
+ display_api_spec(&spec, formatter, writer)?;
+ } else {
+ writeln!(writer, "API '{api_name}' not found in debugfs")?;
+ }
+
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ // Shortened sys_read dump as emitted by kapi_export_json().
+ const SYS_READ_JSON: &str = r#"{
+ "name": "sys_read",
+ "version": 1,
+ "description": "Read data from a file descriptor",
+ "long_description": "",
+ "context_flags": "0x21",
+ "parameters": [
+ {
+ "name": "fd",
+ "type": "unsigned int fd",
+ "type_class": "file_descriptor",
+ "flags": "0x1",
+ "description": "File descriptor to read from ",
+ "constraint_type": "range",
+ "constraint_desc": "Must be a valid, open file descriptor",
+ "min_value": 0,
+ "max_value": 2147483647,
+ "valid_mask": "0x0",
+ "enum_values": [],
+ "size": 0,
+ "alignment": 0,
+ "size_param_idx": null,
+ "size_multiplier": 0
+ },
+ {
+ "name": "buf",
+ "type": "char __user * buf",
+ "type_class": "user_pointer",
+ "flags": "0x42",
+ "description": "User-space buffer to read data into ",
+ "constraint_type": "buffer",
+ "constraint_desc": "Must point to a writable user-space region",
+ "min_value": 0,
+ "max_value": 0,
+ "valid_mask": "0x0",
+ "enum_values": [],
+ "size": 0,
+ "alignment": 0,
+ "size_param_idx": 2,
+ "size_multiplier": 0
+ },
+ {
+ "name": "count",
+ "type": "size_t count",
+ "type_class": "uint",
+ "flags": "0x1",
+ "description": "Maximum number of bytes to read ",
+ "constraint_type": "none",
+ "constraint_desc": "",
+ "min_value": 0,
+ "max_value": 0,
+ "valid_mask": "0x0",
+ "enum_values": [],
+ "size": 0,
+ "alignment": 0,
+ "size_param_idx": null,
+ "size_multiplier": 0
+ }
+ ],
+ "return": {
+ "type": "KAPI_TYPE_INT",
+ "type_class": "int",
+ "check_type": "range",
+ "success_value": 0,
+ "success_min": 0,
+ "success_max": 9223372036854775807,
+ "error_values": [],
+ "description": "Number of bytes read"
+ },
+ "errors": [
+ { "code": -9, "name": "EBADF", "condition": "Bad file descriptor",
+ "description": "fd is not valid" }
+ ],
+ "locks": [
+ { "name": "file->f_pos_lock", "type": "mutex", "scope": "internal",
+ "description": "Position lock" }
+ ],
+ "capabilities": [
+ {
+ "capability": 1,
+ "name": "CAP_DAC_OVERRIDE",
+ "action": "bypass_check",
+ "allows": "Bypass read permission checks",
+ "without_cap": "Standard DAC checks are enforced",
+ "check_condition": "",
+ "priority": 0
+ }
+ ],
+ "constraints": [
+ { "name": "MAX_RW_COUNT",
+ "description": "Count is clamped", "expression": "min(count, MAX_RW_COUNT)" }
+ ],
+ "signals": [
+ {
+ "signal_num": 0,
+ "signal_name": "Any signal",
+ "direction": "0x1",
+ "action": 6,
+ "target": "",
+ "condition": "When blocked waiting for data",
+ "description": "May be interrupted",
+ "restartable": true,
+ "sa_flags_required": "0x0",
+ "sa_flags_forbidden": "0x0",
+ "error_on_signal": -4,
+ "transform_to": 0,
+ "timing": "during",
+ "priority": 0,
+ "interruptible": false,
+ "queue_behavior": "",
+ "state_required": "0x0",
+ "state_forbidden": "0x0"
+ }
+ ],
+ "side_effects": [
+ { "type": "0x10", "target": "file->f_pos", "condition": "",
+ "description": "Offset advances", "reversible": false }
+ ],
+ "state_transitions": [],
+ "signal_masks": [],
+ "struct_specs": [],
+ "examples": "",
+ "notes": ""
+}
+"#;
+
+ // Synthetic dump exercising the fields sys_read leaves empty: enum
+ // values, error values, struct specs, signal masks, state transitions.
+ const FULL_JSON: &str = r#"{
+ "name": "tmp_full",
+ "version": 1,
+ "description": "Full \"feature\" test\tline\nbreak\u0001",
+ "long_description": "",
+ "context_flags": "0x91",
+ "parameters": [
+ {
+ "name": "mode",
+ "type": "int mode",
+ "type_class": "enum",
+ "flags": "0x1",
+ "description": "Enumerated parameter",
+ "constraint_type": "enum",
+ "constraint_desc": "",
+ "min_value": 0,
+ "max_value": 0,
+ "valid_mask": "0x0",
+ "enum_values": [1, 2, -3, 1000000000000],
+ "size": 4096,
+ "alignment": 64,
+ "size_param_idx": null,
+ "size_multiplier": 0
+ },
+ {
+ "name": "bits",
+ "type": "u64 bits",
+ "type_class": "uint",
+ "flags": "0x1",
+ "description": "Masked parameter",
+ "constraint_type": "mask",
+ "constraint_desc": "",
+ "min_value": 0,
+ "max_value": 0,
+ "valid_mask": "0xffffffffffffffff",
+ "enum_values": [],
+ "size": 0,
+ "alignment": 0,
+ "size_param_idx": null,
+ "size_multiplier": 0
+ }
+ ],
+ "return": {
+ "type": "long",
+ "type_class": "int",
+ "check_type": "error_check",
+ "success_value": 0,
+ "success_min": 0,
+ "success_max": 0,
+ "error_values": [-1, -22, -4095],
+ "description": "Error-checked return"
+ },
+ "errors": [],
+ "locks": [
+ { "name": "tmp_lock", "type": "seqlock", "scope": "acquires", "description": "a seqlock" }
+ ],
+ "capabilities": [
+ {
+ "capability": 21,
+ "name": "CAP_SYS_ADMIN",
+ "action": "perform_operation",
+ "allows": "do it",
+ "without_cap": "cannot",
+ "check_condition": "always checked",
+ "priority": 3,
+ "alternatives": [21, 17]
+ }
+ ],
+ "constraints": [],
+ "signals": [],
+ "side_effects": [],
+ "state_transitions": [
+ { "object": "obj", "from_state": "a", "to_state": "b", "condition": "when asked",
+ "description": "moves a to b" }
+ ],
+ "signal_masks": [
+ { "name": "blocked", "description": "Blocked while running", "signals": [2, 15, 3] }
+ ],
+ "struct_specs": [
+ {
+ "name": "tmp_struct",
+ "size": 16,
+ "alignment": 8,
+ "description": "Test structure",
+ "fields": [
+ {
+ "name": "flags",
+ "type": "u32",
+ "type_class": "uint",
+ "offset": 0,
+ "size": 4,
+ "flags": "0x1",
+ "constraint_type": "mask",
+ "min_value": 0,
+ "max_value": 0,
+ "valid_mask": "0xff",
+ "enum_values": "",
+ "description": "Flag bits"
+ },
+ {
+ "name": "kind",
+ "type": "enum k",
+ "type_class": "enum",
+ "offset": 8,
+ "size": 4,
+ "flags": "0x0",
+ "constraint_type": "range",
+ "min_value": -5,
+ "max_value": 5,
+ "valid_mask": "0x0",
+ "enum_values": "",
+ "description": "Kind"
+ }
+ ]
+ }
+ ],
+ "examples": "",
+ "notes": "note"
+}
+"#;
+
+ // Dump without the optional per-parameter constraint fields.
+ const MINIMAL_JSON: &str = r#"{
+ "name": "sys_read",
+ "version": 1,
+ "description": "Read data from a file descriptor",
+ "long_description": "Reads.",
+ "context_flags": "0x21",
+ "parameters": [
+ {
+ "name": "buf",
+ "type": "char __user * buf",
+ "type_class": "user_pointer",
+ "flags": "0x42",
+ "description": "User-space buffer to read data into "
+ }
+ ],
+ "return": {
+ "type": "KAPI_TYPE_INT",
+ "type_class": "int",
+ "check_type": "range",
+ "success_min": 0,
+ "success_max": 9223372036854775807,
+ "description": "Bytes read"
+ },
+ "errors": [],
+ "locks": [],
+ "capabilities": [
+ {
+ "capability": 1,
+ "name": "CAP_DAC_OVERRIDE",
+ "action": "bypass_check",
+ "allows": "a",
+ "without_cap": "b",
+ "check_condition": "c",
+ "priority": 0
+ }
+ ],
+ "constraints": [],
+ "signals": [],
+ "side_effects": [],
+ "examples": "",
+ "notes": ""
+}
+"#;
+
+ fn extractor() -> DebugfsExtractor {
+ DebugfsExtractor {
+ debugfs_path: PathBuf::new(),
+ }
+ }
+
+ #[test]
+ fn json_sys_read_carries_type_and_constraint_data() {
+ let spec = extractor().try_parse_json(SYS_READ_JSON).unwrap();
+
+ assert_eq!(spec.api_type, "syscall");
+ assert_eq!(spec.version.as_deref(), Some("1"));
+ assert_eq!(spec.long_description, None);
+ assert_eq!(
+ spec.context_flags,
+ ["KAPI_CTX_PROCESS", "KAPI_CTX_SLEEPABLE"]
+ );
+ assert_eq!(spec.param_count, Some(3));
+
+ let fd = &spec.parameters[0];
+ assert_eq!((fd.param_type, fd.constraint_type), (9, 1));
+ assert_eq!((fd.min_value, fd.max_value), (Some(0), Some(2147483647)));
+ assert_eq!(fd.valid_mask, None);
+ assert_eq!(fd.size_param_idx, None);
+ assert_eq!(
+ fd.constraint.as_deref(),
+ Some("Must be a valid, open file descriptor")
+ );
+
+ let buf = &spec.parameters[1];
+ assert_eq!((buf.param_type, buf.constraint_type), (10, 11));
+ assert_eq!(buf.flags, 0x42);
+ assert_eq!(buf.size_param_idx, Some(2));
+ assert_eq!(
+ (buf.min_value, buf.max_value, buf.valid_mask),
+ (None, None, None)
+ );
+ assert_eq!((buf.size, buf.alignment), (None, None));
+ assert_eq!(
+ spec.parameters[buf.size_param_idx.unwrap() as usize].name,
+ "count"
+ );
+
+ let count = &spec.parameters[2];
+ assert_eq!((count.param_type, count.constraint_type), (2, 0));
+ assert_eq!(count.constraint, None);
+ assert_eq!(count.description, "Maximum number of bytes to read ");
+
+ let ret = spec.return_spec.as_ref().unwrap();
+ assert_eq!((ret.return_type, ret.check_type), (1, 1));
+ assert_eq!(ret.success_value, None);
+ assert_eq!(ret.success_min, Some(0));
+ assert_eq!(ret.success_max, Some(i64::MAX));
+ assert!(ret.error_values.is_empty());
+
+ assert_eq!(spec.errors[0].error_code, -9);
+ assert_eq!((spec.locks[0].lock_type, spec.locks[0].scope), (1, 0));
+ assert_eq!(spec.capabilities[0].action, "KAPI_CAP_BYPASS_CHECK");
+ assert_eq!(spec.capabilities[0].check_condition, None);
+ assert_eq!(spec.signals[0].timing, 1);
+ assert_eq!(spec.signals[0].error_on_signal, Some(-4));
+ assert_eq!(spec.signals[0].target, None);
+ assert_eq!(spec.side_effects[0].effect_type, 0x10);
+ assert_eq!(spec.side_effects[0].condition, None);
+ assert_eq!(spec.constraints.len(), 1);
+ }
+
+ #[test]
+ fn json_full_carries_enum_error_struct_and_transition_data() {
+ let spec = extractor().try_parse_json(FULL_JSON).unwrap();
+
+ assert_eq!(
+ spec.description.as_deref(),
+ Some("Full \"feature\" test\tline\nbreak\u{1}")
+ );
+ assert_eq!(
+ spec.context_flags,
+ [
+ "KAPI_CTX_PROCESS",
+ "KAPI_CTX_ATOMIC",
+ "KAPI_CTX_IRQ_DISABLED"
+ ]
+ );
+
+ let mode = &spec.parameters[0];
+ assert_eq!((mode.param_type, mode.constraint_type), (6, 3));
+ assert_eq!(mode.enum_values, ["1", "2", "-3", "1000000000000"]);
+ assert_eq!((mode.size, mode.alignment), (Some(4096), Some(64)));
+ assert_eq!(
+ (mode.min_value, mode.max_value, mode.valid_mask),
+ (None, None, None)
+ );
+
+ let bits = &spec.parameters[1];
+ assert_eq!(bits.constraint_type, 2);
+ assert_eq!(bits.valid_mask, Some(u64::MAX));
+ assert_eq!((bits.min_value, bits.max_value), (None, None));
+ assert_eq!((bits.size, bits.alignment), (None, None));
+
+ let ret = spec.return_spec.as_ref().unwrap();
+ assert_eq!(ret.check_type, 2);
+ assert_eq!(ret.error_values, [-1, -22, -4095]);
+
+ assert_eq!(spec.capabilities[0].alternatives, [21, 17]);
+ assert_eq!(spec.capabilities[0].priority, Some(3));
+ assert_eq!((spec.locks[0].lock_type, spec.locks[0].scope), (4, 1));
+
+ let trans = &spec.state_transitions[0];
+ assert_eq!(
+ (trans.object.as_str(), trans.from_state.as_str()),
+ ("obj", "a")
+ );
+ assert_eq!(trans.to_state, "b");
+ assert_eq!(trans.condition.as_deref(), Some("when asked"));
+
+ assert_eq!(spec.signal_masks[0].name, "blocked");
+ assert_eq!(spec.signal_masks[0].signals, [2, 15, 3]);
+
+ let st = &spec.struct_specs[0];
+ assert_eq!(
+ (st.name.as_str(), st.size, st.alignment),
+ ("tmp_struct", 16, 8)
+ );
+ assert_eq!(st.field_count, 2);
+ assert_eq!(st.description, "Test structure");
+ assert_eq!(
+ (st.fields[0].field_type, st.fields[0].constraint_type),
+ (2, 2)
+ );
+ assert_eq!(st.fields[0].valid_mask, 0xff);
+ assert_eq!(st.fields[1].offset, 8);
+ assert_eq!((st.fields[1].min_value, st.fields[1].max_value), (-5, 5));
+ }
+
+ #[test]
+ fn json_without_constraint_fields_still_parses() {
+ let spec = extractor().try_parse_json(MINIMAL_JSON).unwrap();
+
+ let buf = &spec.parameters[0];
+ assert_eq!(buf.param_type, 10);
+ assert_eq!(buf.constraint_type, 0);
+ assert_eq!(buf.min_value, None);
+ assert_eq!(buf.valid_mask, None);
+ assert_eq!(buf.size_param_idx, None);
+ assert!(buf.enum_values.is_empty());
+
+ let ret = spec.return_spec.as_ref().unwrap();
+ assert_eq!((ret.return_type, ret.check_type), (1, 1));
+ assert_eq!(ret.success_value, None);
+ assert_eq!(ret.success_max, Some(i64::MAX));
+ assert_eq!(spec.capabilities[0].action, "KAPI_CAP_BYPASS_CHECK");
+ assert!(spec.state_transitions.is_empty());
+ assert!(spec.struct_specs.is_empty());
+ }
+
+ #[test]
+ fn enum_tokens_match_kernel_numbering() {
+ let classes = [
+ "void",
+ "int",
+ "uint",
+ "pointer",
+ "struct",
+ "union",
+ "enum",
+ "function_pointer",
+ "array",
+ "file_descriptor",
+ "user_pointer",
+ "pathname",
+ "custom",
+ ];
+ for (n, token) in classes.iter().enumerate() {
+ assert_eq!(
+ DebugfsExtractor::parse_type_class(token),
+ n as u32,
+ "{token}"
+ );
+ }
+
+ let constraints = [
+ "none",
+ "range",
+ "mask",
+ "enum",
+ "alignment",
+ "power_of_two",
+ "page_aligned",
+ "nonzero",
+ "user_string",
+ "user_path",
+ "user_ptr",
+ "buffer",
+ "custom",
+ ];
+ for (n, token) in constraints.iter().enumerate() {
+ assert_eq!(
+ DebugfsExtractor::parse_constraint_type(token),
+ n as u32,
+ "{token}"
+ );
+ }
+ }
+
+ #[test]
+ fn api_type_follows_symbol_name() {
+ assert_eq!(DebugfsExtractor::api_type_from_name("sys_read"), "syscall");
+ assert_eq!(DebugfsExtractor::api_type_from_name("foo_ioctl"), "ioctl");
+ assert_eq!(DebugfsExtractor::api_type_from_name("kmalloc"), "function");
+ }
+
+ #[test]
+ fn truncated_json_is_rejected() {
+ let cut = &SYS_READ_JSON[..SYS_READ_JSON.len() / 2];
+ assert!(extractor().try_parse_json(cut).is_err());
+ }
+
+ fn debugfs_with(json: &str, text: &str) -> tempfile::TempDir {
+ let dir = tempfile::tempdir().unwrap();
+ let kapi = dir.path().join("kapi");
+ fs::create_dir_all(kapi.join("specs")).unwrap();
+ fs::create_dir_all(kapi.join("specs-json")).unwrap();
+ fs::write(
+ kapi.join("list"),
+ "Available Kernel API Specifications\n\
+ ===================================\n\n\
+ sys_read - Read data from a file descriptor\n\n\
+ Total: 1 specifications\n",
+ )
+ .unwrap();
+ fs::write(kapi.join("specs-json/sys_read"), json).unwrap();
+ fs::write(kapi.join("specs/sys_read"), text).unwrap();
+ dir
+ }
+
+ #[test]
+ fn reads_json_endpoint_from_debugfs_tree() {
+ let dir = debugfs_with(SYS_READ_JSON, "Name: sys_read\n");
+ let ex = DebugfsExtractor::new(Some(dir.path().to_string_lossy().into_owned())).unwrap();
+ let spec = ex.extract_by_name("sys_read").unwrap().unwrap();
+
+ assert_eq!(spec.parameters[1].constraint_type, 11);
+ assert_eq!(spec.parameters[1].size_param_idx, Some(2));
+ }
+
+ #[test]
+ fn truncated_json_endpoint_falls_back_to_text_dump() {
+ let text = "Name: sys_read\n\
+ Version: 1\n\
+ Description: Read data from a file descriptor\n\
+ Context flags: PROCESS SLEEPABLE \n";
+ let dir = debugfs_with(&SYS_READ_JSON[..SYS_READ_JSON.len() / 2], text);
+ let ex = DebugfsExtractor::new(Some(dir.path().to_string_lossy().into_owned())).unwrap();
+ let spec = ex.extract_by_name("sys_read").unwrap().unwrap();
+
+ assert!(spec.parameters.is_empty());
+ assert_eq!(
+ spec.context_flags,
+ ["KAPI_CTX_PROCESS", "KAPI_CTX_SLEEPABLE"]
+ );
+ }
+
+ #[test]
+ fn text_dump_multi_line_values_stay_in_their_field() {
+ let text = "Kernel API Specification\n\
+ ========================\n\n\
+ Name: sys_read\n\
+ Version: 1\n\
+ Description: Read data from a file descriptor\n\
+ Long description:\n \
+ First paragraph.\n\n \
+ Notes: not a header\n \
+ Version: 9\n\
+ Context flags: PROCESS SLEEPABLE \n\n\
+ Parameters (1):\n \
+ [0] fd:\n \
+ description: File descriptor\n\n\
+ Examples:\n \
+ read(fd, buf, n);\n \
+ close(fd);\n\n\
+ Notes:\n \
+ one\n\n \
+ two\n\n";
+ let dir = debugfs_with("", text);
+ let ex = DebugfsExtractor::new(Some(dir.path().to_string_lossy().into_owned())).unwrap();
+ let spec = ex.extract_by_name("sys_read").unwrap().unwrap();
+
+ assert_eq!(spec.version.as_deref(), Some("1"));
+ assert_eq!(
+ spec.description.as_deref(),
+ Some("Read data from a file descriptor")
+ );
+ assert_eq!(
+ spec.long_description.as_deref(),
+ Some("First paragraph.\n\nNotes: not a header\nVersion: 9")
+ );
+ assert_eq!(
+ spec.context_flags,
+ ["KAPI_CTX_PROCESS", "KAPI_CTX_SLEEPABLE"]
+ );
+ assert_eq!(spec.param_count, Some(1));
+ assert_eq!(
+ spec.examples.as_deref(),
+ Some("read(fd, buf, n);\nclose(fd);")
+ );
+ assert_eq!(spec.notes.as_deref(), Some("one\n\ntwo"));
+ }
+}
--git a/tools/kapi/src/extractor/kerneldoc_parser.rs b/tools/kapi/src/extractor/kerneldoc_parser.rs
new file mode 100644
index 0000000000000..b8fae748470b0
--- /dev/null
+++ b/tools/kapi/src/extractor/kerneldoc_parser.rs
@@ -0,0 +1,3335 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+use super::{
+ ApiSpec, CapabilitySpec, ConstraintSpec, ErrorSpec, LockSpec, ParamSpec, ReturnSpec,
+ SideEffectSpec, SignalSpec, StateTransitionSpec,
+};
+use anyhow::Result;
+use std::collections::HashMap;
+
+/// Kerneldoc parser that extracts KAPI annotations
+pub struct KerneldocParser;
+
+/// What block are we currently inside?
+#[derive(Debug, Clone, PartialEq)]
+enum BlockContext {
+ None,
+ Param(String), // param: <name>
+ Error(String), // error: <name>
+ Signal, // signal: <name>
+ Capability, // capability: <name>
+ SideEffect, // side-effect: <type>
+ StateTransition, // state-trans: ...
+ Constraint, // constraint: <name>
+ Lock, // lock: <name>
+ Return, // return:
+}
+
+/// Evaluate an integer literal exactly as the compiler does on LP64 (int is
+/// 32 bits, long and long long are 64): decimal, 0x/0X hex, 0b/0B binary or
+/// leading-0 octal, an optional u/U/l/L suffix and an optional leading '-'.
+/// The literal's C type (C11 6.4.4.1) decides how '-' wraps, so `-1U` is
+/// 4294967295 and `-0x80000000` is 2147483648. The result is the 64-bit
+/// two's complement pattern the value has once stored into an s64/u64
+/// field. Returns `None` for anything that requires cpp-level constant
+/// resolution (e.g. symbolic masks like `O_RDONLY | O_WRONLY`). Callers must
+/// treat that case as "value unknown" and leave the downstream slot unset,
+/// not store it as 0, which would wrongly assert that zero bits are valid.
+fn eval_c_int_literal(s: &str) -> Option<u64> {
+ let t = s.trim();
+ let (neg, t) = match t.strip_prefix('-') {
+ Some(rest) => (true, rest.trim_start()),
+ None => (false, t),
+ };
+ let body = t.trim_end_matches(['u', 'U', 'l', 'L']);
+ let suffix = &t[body.len()..];
+ let unsigned = match suffix.matches(['u', 'U']).count() {
+ 0 => false,
+ 1 => true,
+ _ => return None,
+ };
+ let longs = suffix.matches(['l', 'L']).count();
+ if longs > 2 {
+ return None;
+ }
+
+ let (digits, radix) =
+ if let Some(h) = body.strip_prefix("0x").or_else(|| body.strip_prefix("0X")) {
+ (h, 16)
+ } else if let Some(b) = body.strip_prefix("0b").or_else(|| body.strip_prefix("0B")) {
+ (b, 2)
+ } else if body.len() > 1 && body.starts_with('0') {
+ (&body[1..], 8)
+ } else {
+ (body, 10)
+ };
+ if digits.is_empty() || !digits.chars().all(|c| c.is_digit(radix)) {
+ return None;
+ }
+ let v = u64::from_str_radix(digits, radix).ok()?;
+
+ // Decimal literals without 'u' only take signed types; GCC treats one
+ // too large for long long as unsigned.
+ let value = if longs == 0 && !unsigned && v <= i32::MAX as u64 {
+ let x = v as i32;
+ (if neg { x.wrapping_neg() } else { x }) as i64 as u64
+ } else if longs == 0 && (unsigned || radix != 10) && v <= u32::MAX as u64 {
+ let x = v as u32;
+ u64::from(if neg { x.wrapping_neg() } else { x })
+ } else if !unsigned && v <= i64::MAX as u64 {
+ let x = v as i64;
+ (if neg { x.wrapping_neg() } else { x }) as u64
+ } else if neg {
+ v.wrapping_neg()
+ } else {
+ v
+ };
+ Some(value)
+}
+
+fn parse_u64_literal(s: &str) -> Option<u64> {
+ eval_c_int_literal(s)
+}
+
+fn parse_i64_literal(s: &str) -> Option<i64> {
+ eval_c_int_literal(s).map(|v| v as i64)
+}
+
+/// Split a return `success:` value into (exact value, range minimum,
+/// range maximum). `>= N` is the range [N, i64::MAX]; `N`, `= N` and
+/// `== N` are an exact value, and any value that is not `>= N` leaves
+/// the default range [0, i64::MAX] a range check falls back to. Mirrors
+/// `_return_success_macro()` in kdoc_apispec.py.
+fn parse_return_success(text: &str) -> (Option<i64>, Option<i64>, Option<i64>) {
+ let t = text.trim();
+ if let Some(min) = t.strip_prefix(">=") {
+ return (
+ None,
+ Some(parse_i64_literal(min).unwrap_or(0)),
+ Some(i64::MAX),
+ );
+ }
+ let exact = t
+ .strip_prefix("==")
+ .or_else(|| t.strip_prefix('='))
+ .unwrap_or(t);
+ (parse_i64_literal(exact), Some(0), Some(i64::MAX))
+}
+
+/// Canonicalise a capability `type:` value to its KAPI_CAP_* spelling.
+fn canon_kapi_cap_action(s: &str) -> String {
+ let t = s.trim();
+ if t.starts_with("KAPI_CAP_") {
+ return t.to_string();
+ }
+ match t.to_ascii_lowercase().as_str() {
+ "bypass_check" => "KAPI_CAP_BYPASS_CHECK".to_string(),
+ "increase_limit" => "KAPI_CAP_INCREASE_LIMIT".to_string(),
+ "override_restriction" => "KAPI_CAP_OVERRIDE_RESTRICTION".to_string(),
+ "grant_permission" => "KAPI_CAP_GRANT_PERMISSION".to_string(),
+ "modify_behavior" => "KAPI_CAP_MODIFY_BEHAVIOR".to_string(),
+ "access_resource" => "KAPI_CAP_ACCESS_RESOURCE".to_string(),
+ "perform_operation" => "KAPI_CAP_PERFORM_OPERATION".to_string(),
+ _ => t.to_string(),
+ }
+}
+
+/// Types whose semantics imply `KAPI_PARAM_USER` on the param, so
+/// `type: user_ptr, input` doesn't need a separate `user` flag.
+fn type_implies_user_flag(tok: &str) -> bool {
+ matches!(tok.trim(), "KAPI_TYPE_USER_PTR" | "KAPI_TYPE_PATH")
+ || matches!(
+ tok.trim().to_ascii_lowercase().as_str(),
+ "user_ptr" | "uptr" | "path"
+ )
+}
+
+/// Subfield names each block type consumes. An indented line opens a
+/// new subfield only when it starts with one of these followed by ':';
+/// any other line continues the previous subfield. Must stay in sync
+/// with the `_*_SUBFIELDS` sets in tools/lib/python/kdoc/kdoc_apispec.py.
+fn block_subfield_keys(block: &BlockContext) -> &'static [&'static str] {
+ match block {
+ BlockContext::Param(_) => &[
+ "type",
+ "flags",
+ "size",
+ "constraint-type",
+ "constraint",
+ "cdesc",
+ "range",
+ "mask",
+ "valid-mask",
+ "valid-values",
+ "alignment",
+ "size-param",
+ "struct-type",
+ "arch-mask",
+ "desc",
+ "description",
+ ],
+ BlockContext::Error(_) => &["desc", "condition"],
+ BlockContext::Signal => &[
+ "direction",
+ "action",
+ "condition",
+ "desc",
+ "errno",
+ "timing",
+ "priority",
+ "restartable",
+ "interruptible",
+ "number",
+ "target",
+ "queue",
+ "queue_behavior",
+ "transform",
+ "transform_to",
+ "transform-to",
+ "sa_flags_required",
+ "sa-flags-required",
+ "sa_flags_forbidden",
+ "sa-flags-forbidden",
+ "state_required",
+ "state-required",
+ "state_forbidden",
+ "state-forbidden",
+ ],
+ BlockContext::Capability => &["type", "allows", "without", "condition", "priority", "desc"],
+ BlockContext::SideEffect => &["target", "desc", "condition", "reversible"],
+ BlockContext::StateTransition => &["object", "from", "to", "condition", "desc"],
+ BlockContext::Constraint => &["desc", "expr"],
+ BlockContext::Lock => &[
+ "type",
+ "scope",
+ "acquired",
+ "released",
+ "held-on-entry",
+ "held-on-exit",
+ "desc",
+ ],
+ BlockContext::Return => &[
+ "type",
+ "check-type",
+ "success",
+ "success-range",
+ "error-values",
+ "desc",
+ ],
+ BlockContext::None => &[],
+ }
+}
+
+/// True if `line` starts with one of `keys` followed by ':'.
+fn starts_subfield(line: &str, keys: &[&str]) -> bool {
+ line.split_once(':')
+ .is_some_and(|(key, _)| keys.contains(&key.trim()))
+}
+
+fn is_indented_line(line: &str) -> bool {
+ line.starts_with(" ") || line.starts_with('\t')
+}
+
+/// Fold free-form prose into paragraphs. Blank lines separate
+/// paragraphs ("\n\n"); wrapped lines inside a paragraph are joined
+/// with spaces, except that a line starting with "- " always begins a
+/// new line so bullet lists survive. Mirrors `_fold_paragraphs()` in
+/// kdoc_apispec.py.
+fn fold_paragraphs(lines: &[&str]) -> String {
+ let mut paragraphs: Vec<Vec<String>> = Vec::new();
+ let mut current: Vec<String> = Vec::new();
+ for line in lines {
+ let line = line.trim();
+ if line.is_empty() {
+ if !current.is_empty() {
+ paragraphs.push(std::mem::take(&mut current));
+ }
+ } else if line.starts_with("- ") || current.is_empty() {
+ current.push(line.to_string());
+ } else if let Some(last) = current.last_mut() {
+ last.push(' ');
+ last.push_str(line);
+ }
+ }
+ if !current.is_empty() {
+ paragraphs.push(current);
+ }
+ paragraphs
+ .iter()
+ .map(|p| p.join("\n"))
+ .collect::<Vec<_>>()
+ .join("\n\n")
+ .replace('\t', " ")
+}
+
+fn expand_tabs(line: &str) -> String {
+ let mut out = String::with_capacity(line.len());
+ let mut col = 0;
+ for c in line.chars() {
+ if c == '\t' {
+ let pad = 8 - col % 8;
+ out.extend(std::iter::repeat_n(' ', pad));
+ col += pad;
+ } else {
+ out.push(c);
+ col += 1;
+ }
+ }
+ out
+}
+
+/// Keep every line of a block on its own line. The indentation shared
+/// by the continuation lines is removed so relative indentation
+/// (nested code) is preserved; runs of blank lines collapse into one.
+/// Mirrors `_fold_lines()` in kdoc_apispec.py.
+fn fold_lines(lines: &[&str]) -> String {
+ let mut lines: Vec<String> = lines
+ .iter()
+ .map(|l| expand_tabs(l).trim_end().to_string())
+ .collect();
+ while lines.first().is_some_and(|l| l.is_empty()) {
+ lines.remove(0);
+ }
+ while lines.last().is_some_and(|l| l.is_empty()) {
+ lines.pop();
+ }
+
+ let indent = |l: &str| l.len() - l.trim_start().len();
+ let base = lines
+ .iter()
+ .skip(1)
+ .filter(|l| !l.is_empty())
+ .map(|l| indent(l))
+ .min()
+ .unwrap_or(0);
+
+ let mut out: Vec<&str> = Vec::new();
+ for line in &lines {
+ if line.is_empty() {
+ if out.last().is_some_and(|l| l.is_empty()) {
+ continue;
+ }
+ out.push("");
+ } else {
+ out.push(&line[base.min(indent(line))..]);
+ }
+ }
+ out.join("\n")
+}
+
+impl KerneldocParser {
+ pub fn new() -> Self {
+ KerneldocParser
+ }
+
+ pub fn parse_kerneldoc(
+ &self,
+ doc: &str,
+ name: &str,
+ api_type: &str,
+ signature: Option<&str>,
+ ) -> Result<ApiSpec> {
+ let mut spec = ApiSpec {
+ name: name.to_string(),
+ api_type: api_type.to_string(),
+ ..Default::default()
+ };
+
+ let lines: Vec<&str> = doc.lines().collect();
+
+ // Extract main description from function name line
+ if let Some(first_line) = lines.first() {
+ if let Some((_, desc)) = first_line.split_once(" - ") {
+ spec.description = Some(desc.trim().to_string());
+ }
+ }
+
+ // Extract type names from SYSCALL_DEFINE signature
+ let type_map = if let Some(sig) = signature {
+ self.extract_types_from_signature(sig)
+ } else {
+ HashMap::new()
+ };
+
+ // Keep track of parameters we've seen (from @param lines)
+ let mut param_map: HashMap<String, ParamSpec> = HashMap::new();
+
+ // Current block being parsed
+ let mut block = BlockContext::None;
+
+ // Temporary storage for current block items
+ let mut current_lock: Option<LockSpec> = None;
+ let mut current_signal: Option<SignalSpec> = None;
+ // Pending symbolic `transform-to:` token. Captured when the parser
+ // sees a non-numeric value, but only reported if the final
+ // `transform_to` after all lines in the signal block is still
+ // unresolved. A later numeric `transform-to:` clears this so we
+ // don't warn about a value that was subsequently overridden.
+ let mut pending_transform_warning: Option<String> = None;
+ let mut current_capability: Option<CapabilitySpec> = None;
+ let mut current_side_effect: Option<SideEffectSpec> = None;
+ let mut current_constraint: Option<ConstraintSpec> = None;
+ let mut current_error: Option<ErrorSpec> = None;
+ let mut current_return: Option<ReturnSpec> = None;
+ let mut current_state_trans: Option<StateTransitionSpec> = None;
+
+ let mut i = 0;
+
+ while i < lines.len() {
+ let line = lines[i];
+ let trimmed = line.trim();
+
+ // Skip empty lines
+ if trimmed.is_empty() {
+ i += 1;
+ continue;
+ }
+
+ // Check if this is an indented continuation line (part of current block)
+ let is_indented = is_indented_line(line);
+
+ // If indented and we're in a block, parse as block attribute.
+ // A subfield line absorbs the lines that follow it until the
+ // next known subfield key, so a value such as
+ // `constraint-type: mask(FOO | BAR |` ... `| BAZ)` or a
+ // wrapped `condition:` arrives as a single logical line.
+ if is_indented && block != BlockContext::None {
+ let keys = block_subfield_keys(&block);
+ let mut logical = trimmed.to_string();
+ if starts_subfield(trimmed, keys) {
+ let mut j = i + 1;
+ while j < lines.len() {
+ let next = lines[j];
+ let next_trim = next.trim();
+ if next_trim.is_empty() {
+ j += 1;
+ continue;
+ }
+ if !is_indented_line(next) || starts_subfield(next_trim, keys) {
+ break;
+ }
+ logical.push(' ');
+ logical.push_str(next_trim);
+ i = j;
+ j += 1;
+ }
+ }
+ self.parse_block_attribute(
+ &logical,
+ &block,
+ &mut param_map,
+ &mut current_error,
+ &mut current_signal,
+ &mut pending_transform_warning,
+ &mut current_capability,
+ &mut current_side_effect,
+ &mut current_constraint,
+ &mut current_lock,
+ &mut current_return,
+ &mut current_state_trans,
+ );
+ i += 1;
+ continue;
+ }
+
+ // Not indented or not in block: flush current block if any.
+ // If a symbolic `transform-to:` was captured and no later
+ // numeric line cleared it, surface the warning now; by
+ // construction `transform_to` is None in that case.
+ if matches!(block, BlockContext::Signal) {
+ if let Some(raw) = pending_transform_warning.take() {
+ eprintln!(
+ "kapi: warning: transform-to: {raw:?} is symbolic; \
+ source-mode cannot resolve signal numbers portably. \
+ Use --vmlinux or --debugfs to get the resolved value.",
+ );
+ }
+ }
+ self.flush_block(
+ &mut block,
+ &mut spec,
+ &mut current_error,
+ &mut current_signal,
+ &mut current_capability,
+ &mut current_side_effect,
+ &mut current_constraint,
+ &mut current_lock,
+ &mut current_return,
+ &mut current_state_trans,
+ );
+
+ // Parse top-level annotations
+ if let Some(rest) = trimmed.strip_prefix("@") {
+ // @param: description (standard kerneldoc parameter)
+ if let Some((param_name, desc)) = rest.split_once(':') {
+ let param_name = param_name.trim();
+ let desc = desc.trim();
+ if !param_name.contains('-') {
+ let idx = param_map.len() as u32;
+ let type_name = type_map.get(param_name).cloned().unwrap_or_default();
+ param_map.insert(
+ param_name.to_string(),
+ ParamSpec {
+ index: idx,
+ name: param_name.to_string(),
+ type_name,
+ description: desc.to_string(),
+ flags: 0,
+ param_type: 0,
+ constraint_type: 0,
+ constraint: None,
+ min_value: None,
+ max_value: None,
+ valid_mask: None,
+ enum_values: vec![],
+ size: None,
+ alignment: None,
+ size_param_idx: None,
+ },
+ );
+ }
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("long-desc:") {
+ let (section, next_i) = self.collect_section(&lines, i, rest);
+ let val = fold_paragraphs(§ion);
+ spec.long_description = Some(val).filter(|v| !v.is_empty());
+ i = next_i;
+ continue;
+ } else if let Some(rest) = trimmed.strip_prefix("context-flags:") {
+ spec.context_flags = self.parse_context_flags(rest.trim());
+ } else if let Some(rest) = trimmed.strip_prefix("contexts:") {
+ // Short form: "contexts: process, sleepable"
+ spec.context_flags = self.parse_context_list(rest.trim());
+ } else if let Some(rest) = trimmed.strip_prefix("param-count:") {
+ spec.param_count = rest.trim().parse().ok();
+ }
+ // Block-start annotations
+ else if let Some(rest) = trimmed.strip_prefix("param:") {
+ let param_name = rest.trim().to_string();
+ block = BlockContext::Param(param_name.clone());
+ // Ensure param exists in map
+ if !param_map.contains_key(¶m_name) {
+ let idx = param_map.len() as u32;
+ let type_name = type_map
+ .get(param_name.as_str())
+ .cloned()
+ .unwrap_or_default();
+ param_map.insert(
+ param_name.clone(),
+ ParamSpec {
+ index: idx,
+ name: param_name,
+ type_name,
+ description: String::new(),
+ flags: 0,
+ param_type: 0,
+ constraint_type: 0,
+ constraint: None,
+ min_value: None,
+ max_value: None,
+ valid_mask: None,
+ enum_values: vec![],
+ size: None,
+ alignment: None,
+ size_param_idx: None,
+ },
+ );
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("error:") {
+ // error: NAME, condition
+ let parts: Vec<&str> = rest.splitn(2, ',').map(|s| s.trim()).collect();
+ if !parts.is_empty() {
+ let error_name = parts[0].to_string();
+ let condition = if parts.len() >= 2 {
+ parts[1].to_string()
+ } else {
+ String::new()
+ };
+ let error_code = self.error_name_to_code(&error_name);
+ current_error = Some(ErrorSpec {
+ error_code,
+ name: error_name.clone(),
+ condition,
+ description: String::new(),
+ });
+ block = BlockContext::Error(error_name);
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("signal:") {
+ let signal_name = rest.trim().to_string();
+ current_signal = Some(SignalSpec {
+ signal_num: 0,
+ signal_name,
+ direction: 1,
+ action: 0,
+ target: None,
+ condition: None,
+ description: None,
+ restartable: false,
+ timing: 0,
+ priority: 0,
+ interruptible: false,
+ queue: None,
+ sa_flags: 0,
+ sa_flags_required: 0,
+ sa_flags_forbidden: 0,
+ state_required: 0,
+ state_forbidden: 0,
+ error_on_signal: None,
+ transform_to: None,
+ });
+ block = BlockContext::Signal;
+ } else if let Some(rest) = trimmed.strip_prefix("capability:") {
+ let parts: Vec<&str> = rest.split(',').map(|s| s.trim()).collect();
+ if !parts.is_empty() {
+ let cap_name = parts[0].to_string();
+ let cap_value = self.parse_capability_value(&cap_name);
+ // If we have 3 parts, it's flat format: capability: CAP, action, name
+ let (action, name) = if parts.len() >= 3 {
+ (parts[1].to_string(), parts[2].to_string())
+ } else {
+ (String::new(), cap_name.clone())
+ };
+ current_capability = Some(CapabilitySpec {
+ capability: cap_value,
+ name,
+ action,
+ allows: String::new(),
+ without_cap: String::new(),
+ check_condition: None,
+ priority: Some(0),
+ alternatives: vec![],
+ });
+ block = BlockContext::Capability;
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("side-effect:") {
+ // Could be flat format (comma-separated) or block start
+ let rest = rest.trim();
+ // Check if it's the flat format with commas
+ let comma_parts: Vec<&str> = rest.splitn(3, ',').map(|s| s.trim()).collect();
+ if comma_parts.len() >= 3 {
+ // Flat format: side-effect: TYPE, target, desc
+ let mut effect = SideEffectSpec {
+ effect_type: self.parse_effect_type(comma_parts[0]),
+ target: comma_parts[1].to_string(),
+ condition: None,
+ description: comma_parts[2].to_string(),
+ reversible: false,
+ };
+ if comma_parts[2].contains("reversible=yes") {
+ effect.reversible = true;
+ }
+ spec.side_effects.push(effect);
+ } else {
+ // Block format: side-effect: TYPE
+ current_side_effect = Some(SideEffectSpec {
+ effect_type: self.parse_effect_type(rest),
+ target: String::new(),
+ condition: None,
+ description: String::new(),
+ reversible: false,
+ });
+ block = BlockContext::SideEffect;
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("state-trans:") {
+ // Flat form: state-trans: OBJECT, FROM, TO, DESCRIPTION
+ // (the description may itself contain commas). Block
+ // form: a bare OBJECT followed by from:/to:/condition:/
+ // desc: subfields.
+ if rest.contains(',') {
+ let mut parts = rest.splitn(4, ',').map(|s| s.trim());
+ let mut next_part = || parts.next().unwrap_or_default().to_string();
+ spec.state_transitions.push(StateTransitionSpec {
+ object: next_part(),
+ from_state: next_part(),
+ to_state: next_part(),
+ condition: None,
+ description: next_part(),
+ });
+ } else {
+ current_state_trans = Some(StateTransitionSpec {
+ object: rest.trim().to_string(),
+ from_state: String::new(),
+ to_state: String::new(),
+ condition: None,
+ description: String::new(),
+ });
+ }
+ block = BlockContext::StateTransition;
+ } else if let Some(rest) = trimmed.strip_prefix("constraint:") {
+ let rest = rest.trim();
+ // Could be flat format: constraint: name, desc
+ // Or block format: constraint: name
+ let parts: Vec<&str> = rest.splitn(2, ',').map(|s| s.trim()).collect();
+ if parts.len() >= 2 {
+ // Flat format
+ current_constraint = Some(ConstraintSpec {
+ name: parts[0].to_string(),
+ description: parts[1].to_string(),
+ expression: None,
+ });
+ } else {
+ // Block format
+ current_constraint = Some(ConstraintSpec {
+ name: rest.to_string(),
+ description: String::new(),
+ expression: None,
+ });
+ }
+ block = BlockContext::Constraint;
+ } else if let Some(rest) = trimmed.strip_prefix("lock:") {
+ let rest = rest.trim();
+ // Could be flat: lock: name, type
+ // Or block: lock: name
+ let parts: Vec<&str> = rest.split(',').map(|s| s.trim()).collect();
+ if parts.len() >= 2 {
+ current_lock = Some(LockSpec {
+ lock_name: parts[0].to_string(),
+ lock_type: self.parse_lock_type(parts[1]),
+ scope: super::KAPI_LOCK_INTERNAL,
+ description: String::new(),
+ });
+ } else {
+ current_lock = Some(LockSpec {
+ lock_name: rest.to_string(),
+ lock_type: 0,
+ scope: super::KAPI_LOCK_INTERNAL,
+ description: String::new(),
+ });
+ }
+ block = BlockContext::Lock;
+ }
+ // Other top-level annotations
+ else if let Some(rest) = trimmed.strip_prefix("return:") {
+ let rest = rest.trim();
+ if rest.is_empty() {
+ // Block format
+ current_return = Some(ReturnSpec {
+ type_name: String::new(),
+ description: String::new(),
+ return_type: 0,
+ check_type: 0,
+ success_value: None,
+ success_min: None,
+ success_max: None,
+ error_values: vec![],
+ });
+ block = BlockContext::Return;
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("examples:") {
+ let (section, next_i) = self.collect_section(&lines, i, rest);
+ let val = fold_lines(§ion);
+ spec.examples = Some(val).filter(|v| !v.is_empty());
+ i = next_i;
+ continue;
+ } else if let Some(rest) = trimmed.strip_prefix("notes:") {
+ let (section, next_i) = self.collect_section(&lines, i, rest);
+ let val = fold_paragraphs(§ion);
+ spec.notes = Some(val).filter(|v| !v.is_empty());
+ i = next_i;
+ continue;
+ }
+
+ i += 1;
+ }
+
+ // Flush any remaining block. Emit a pending symbolic
+ // `transform-to:` warning if the final state still has no
+ // resolved numeric value (see per-line loop for rationale).
+ if matches!(block, BlockContext::Signal) {
+ if let Some(raw) = pending_transform_warning.take() {
+ eprintln!(
+ "kapi: warning: transform-to: {raw:?} is symbolic; \
+ source-mode cannot resolve signal numbers portably. \
+ Use --vmlinux or --debugfs to get the resolved value.",
+ );
+ }
+ }
+ self.flush_block(
+ &mut block,
+ &mut spec,
+ &mut current_error,
+ &mut current_signal,
+ &mut current_capability,
+ &mut current_side_effect,
+ &mut current_constraint,
+ &mut current_lock,
+ &mut current_return,
+ &mut current_state_trans,
+ );
+
+ // Convert param_map to vec preserving order
+ let mut params: Vec<ParamSpec> = param_map.into_values().collect();
+ params.sort_by_key(|p| p.index);
+
+ // If the spec carries an explicit param-count, warn when it
+ // disagrees with the number of param: blocks we actually saw.
+ if let Some(claimed) = spec.param_count {
+ if claimed as usize != params.len() {
+ eprintln!(
+ "kapi: {}: param-count: {} disagrees with {} param: block(s)",
+ name,
+ claimed,
+ params.len(),
+ );
+ }
+ }
+
+ for param in &mut params {
+ param.drop_unset_string_limits();
+ }
+ spec.parameters = params;
+
+ Ok(spec)
+ }
+
+ /// Parse an indented attribute line within a block
+ #[allow(clippy::too_many_arguments)]
+ fn parse_block_attribute(
+ &self,
+ trimmed: &str,
+ block: &BlockContext,
+ param_map: &mut HashMap<String, ParamSpec>,
+ current_error: &mut Option<ErrorSpec>,
+ current_signal: &mut Option<SignalSpec>,
+ pending_transform_warning: &mut Option<String>,
+ current_capability: &mut Option<CapabilitySpec>,
+ current_side_effect: &mut Option<SideEffectSpec>,
+ current_constraint: &mut Option<ConstraintSpec>,
+ current_lock: &mut Option<LockSpec>,
+ current_return: &mut Option<ReturnSpec>,
+ current_state_trans: &mut Option<StateTransitionSpec>,
+ ) {
+ match block {
+ BlockContext::Param(param_name) => {
+ if let Some(param) = param_map.get_mut(param_name) {
+ if let Some(rest) = trimmed.strip_prefix("type:") {
+ // Accept either:
+ // type: KAPI_TYPE_UINT (long, single token)
+ // type: uint (short, single token)
+ // type: uint, input (short, type + flags)
+ // type: path, input (short, type + flags)
+ // Single-token inputs leave flags alone; they are
+ // set by a separate `flags:` line.
+ //
+ // User-space pointer types (user_ptr, path) imply
+ // KAPI_PARAM_USER, so specs don't need to repeat
+ // `user` after the type.
+ let mut parts = rest.split(',').map(str::trim);
+ let type_token = parts.next();
+ if let Some(ty) = type_token {
+ param.param_type = self.parse_param_type(ty);
+ }
+ for flag in parts {
+ param.flags |= self.parse_param_flag_token(flag);
+ }
+ if type_token.map(type_implies_user_flag).unwrap_or(false) {
+ param.flags |= 1 << 6; // KAPI_PARAM_USER
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("flags:") {
+ param.flags = self.parse_param_flags(rest.trim());
+ } else if let Some(rest) = trimmed.strip_prefix("constraint-type:") {
+ // Accepts `KAPI_CONSTRAINT_*` enum tokens or
+ // function-call expressions like `range(0, 4096)`
+ // / `mask(0xff)` / `buffer(2)` that also populate
+ // the matching numeric fields on `param`.
+ let text = rest.trim();
+ if !self.apply_constraint_expr(param, text) {
+ param.constraint_type = self.parse_constraint_type(text);
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("valid-mask:") {
+ // Symbolic mask values need cpp-level resolution;
+ // leave that to the binary reader.
+ let _ = rest;
+ } else if let Some(rest) = trimmed
+ .strip_prefix("cdesc:")
+ .or_else(|| trimmed.strip_prefix("constraint:"))
+ {
+ // Free-text constraint description.
+ param.constraint = Some(rest.trim().to_string());
+ } else if let Some(rest) = trimmed.strip_prefix("range:") {
+ let parts: Vec<&str> = rest.split(',').map(|s| s.trim()).collect();
+ if parts.len() >= 2 {
+ param.min_value = parts[0].parse().ok();
+ param.max_value = parts[1].parse().ok();
+ param.constraint_type = 1; // KAPI_CONSTRAINT_RANGE
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("size-param:") {
+ param.size_param_idx = rest.trim().parse().ok();
+ } else if let Some(rest) = trimmed.strip_prefix("description:") {
+ param.description = rest.trim().to_string();
+ } else if let Some(rest) = trimmed.strip_prefix("desc:") {
+ param.description = rest.trim().to_string();
+ } else if !trimmed.contains(':') || trimmed.starts_with(" ") {
+ // Continuation of the previous attribute's value.
+ if let Some(c) = param.constraint.as_mut() {
+ c.push(' ');
+ c.push_str(trimmed);
+ }
+ }
+ }
+ }
+ BlockContext::Error(_) => {
+ if let Some(error) = current_error.as_mut() {
+ if let Some(rest) = trimmed.strip_prefix("desc:") {
+ let text = rest.trim().to_string();
+ if error.description.is_empty() {
+ error.description = text;
+ } else {
+ error.description.push(' ');
+ error.description.push_str(&text);
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("condition:") {
+ error.condition = rest.trim().to_string();
+ } else {
+ // Continuation of description
+ if !error.description.is_empty() {
+ error.description.push(' ');
+ error.description.push_str(trimmed);
+ }
+ }
+ }
+ }
+ BlockContext::Signal => {
+ if let Some(signal) = current_signal.as_mut() {
+ if let Some(rest) = trimmed.strip_prefix("direction:") {
+ signal.direction = self.parse_signal_direction(rest.trim());
+ } else if let Some(rest) = trimmed.strip_prefix("action:") {
+ signal.action = self.parse_signal_action(rest.trim());
+ } else if let Some(rest) = trimmed.strip_prefix("condition:") {
+ signal.condition = Some(rest.trim().to_string());
+ } else if let Some(rest) = trimmed.strip_prefix("desc:") {
+ let text = rest.trim().to_string();
+ if signal.description.is_none() {
+ signal.description = Some(text);
+ } else if let Some(d) = signal.description.as_mut() {
+ d.push(' ');
+ d.push_str(&text);
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("errno:") {
+ // `error:` cannot be used here because kerneldoc
+ // promotes it to a top-level section header.
+ //
+ // Accepted forms:
+ // errno: -4 -> numeric literal, stored as-is
+ // errno: -EINTR -> kernel convention; resolve
+ // the symbol and negate
+ // errno: EINTR -> bare symbol; resolved value
+ // is already negative
+ let value = rest.trim();
+ signal.error_on_signal = if let Ok(code) = value.parse::<i32>() {
+ Some(code)
+ } else if let Some(name) = value.strip_prefix('-') {
+ // `error_name_to_code` already returns the negated
+ // code (e.g. "EINTR" -> -4), so `-EINTR` resolves
+ // to -4 too; the leading `-` on the symbolic form
+ // is kernel-source convention, not a second negation.
+ Some(self.error_name_to_code(name))
+ } else {
+ Some(self.error_name_to_code(value))
+ };
+ } else if let Some(rest) = trimmed.strip_prefix("timing:") {
+ signal.timing = self.parse_signal_timing(rest.trim());
+ } else if let Some(rest) = trimmed.strip_prefix("restartable:") {
+ let val = rest.trim().to_lowercase();
+ signal.restartable = matches!(val.as_str(), "yes" | "true" | "1");
+ } else if let Some(rest) = trimmed.strip_prefix("interruptible:") {
+ let val = rest.trim().to_lowercase();
+ signal.interruptible = matches!(val.as_str(), "yes" | "true" | "1");
+ } else if let Some(rest) = trimmed.strip_prefix("priority:") {
+ signal.priority = rest.trim().parse().unwrap_or(0);
+ } else if let Some(rest) = trimmed.strip_prefix("target:") {
+ signal.target = Some(rest.trim().to_string());
+ } else if let Some(rest) = trimmed
+ .strip_prefix("queue:")
+ .or_else(|| trimmed.strip_prefix("queue_behavior:"))
+ {
+ signal.queue = Some(rest.trim().to_string());
+ } else if let Some(rest) = trimmed.strip_prefix("number:") {
+ signal.signal_num = rest.trim().parse().unwrap_or(0);
+ } else if let Some(rest) = trimmed
+ .strip_prefix("transform-to:")
+ .or_else(|| trimmed.strip_prefix("transform_to:"))
+ .or_else(|| trimmed.strip_prefix("transform:"))
+ {
+ // transform-to: takes a signal constant (e.g.
+ // SIGKILL) or a numeric literal. Only a numeric
+ // literal fills `transform_to`; symbolic values
+ // cannot be resolved portably in userspace
+ // because signal numbers are arch-dependent and
+ // we have no access to the target arch's
+ // <asm/signal.h>. Report such cases to stderr so
+ // they are not silently lost, and point the user
+ // at --vmlinux / --debugfs, which consult the
+ // compiled struct where the C preprocessor has
+ // already baked in the correct value.
+ //
+ // Assign unconditionally so the last line in
+ // the kerneldoc wins and an intended symbolic
+ // override doesn't silently leave a stale
+ // numeric value from an earlier line. The
+ // warning is deferred until flush_block() so a
+ // subsequent numeric line can cancel it; if the
+ // last line was still symbolic we report it
+ // then.
+ let v = rest.trim();
+ let parsed = v.parse::<i32>().ok();
+ signal.transform_to = parsed;
+ if parsed.is_some() {
+ *pending_transform_warning = None;
+ } else if !v.is_empty() {
+ *pending_transform_warning = Some(v.to_string());
+ }
+ } else if let Some(rest) = trimmed
+ .strip_prefix("sa-flags-required:")
+ .or_else(|| trimmed.strip_prefix("sa_flags_required:"))
+ {
+ signal.sa_flags_required = self.parse_hex_or_bitmask(rest.trim());
+ } else if let Some(rest) = trimmed
+ .strip_prefix("sa-flags-forbidden:")
+ .or_else(|| trimmed.strip_prefix("sa_flags_forbidden:"))
+ {
+ signal.sa_flags_forbidden = self.parse_hex_or_bitmask(rest.trim());
+ } else if let Some(rest) = trimmed
+ .strip_prefix("state-required:")
+ .or_else(|| trimmed.strip_prefix("state_required:"))
+ {
+ signal.state_required = self.parse_signal_state_mask(rest.trim());
+ } else if let Some(rest) = trimmed
+ .strip_prefix("state-forbidden:")
+ .or_else(|| trimmed.strip_prefix("state_forbidden:"))
+ {
+ signal.state_forbidden = self.parse_signal_state_mask(rest.trim());
+ } else {
+ // Continuation of description
+ if let Some(d) = signal.description.as_mut() {
+ d.push(' ');
+ d.push_str(trimmed);
+ }
+ }
+ }
+ }
+ BlockContext::Capability => {
+ if let Some(cap) = current_capability.as_mut() {
+ if let Some(rest) = trimmed.strip_prefix("type:") {
+ cap.action = canon_kapi_cap_action(rest.trim());
+ } else if let Some(rest) = trimmed.strip_prefix("allows:") {
+ cap.allows = rest.trim().to_string();
+ } else if let Some(rest) = trimmed.strip_prefix("without:") {
+ cap.without_cap = rest.trim().to_string();
+ } else if let Some(rest) = trimmed.strip_prefix("condition:") {
+ cap.check_condition = Some(rest.trim().to_string());
+ } else if let Some(rest) = trimmed.strip_prefix("priority:") {
+ cap.priority = rest.trim().parse().ok();
+ }
+ }
+ }
+ BlockContext::SideEffect => {
+ if let Some(effect) = current_side_effect.as_mut() {
+ if let Some(rest) = trimmed.strip_prefix("target:") {
+ effect.target = rest.trim().to_string();
+ } else if let Some(rest) = trimmed.strip_prefix("condition:") {
+ effect.condition = Some(rest.trim().to_string());
+ } else if let Some(rest) = trimmed.strip_prefix("desc:") {
+ let text = rest.trim().to_string();
+ if effect.description.is_empty() {
+ effect.description = text;
+ } else {
+ effect.description.push(' ');
+ effect.description.push_str(&text);
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("reversible:") {
+ let val = rest.trim().to_lowercase();
+ effect.reversible = matches!(val.as_str(), "yes" | "true" | "1");
+ } else {
+ // Continuation of description
+ if !effect.description.is_empty() {
+ effect.description.push(' ');
+ effect.description.push_str(trimmed);
+ }
+ }
+ }
+ }
+ BlockContext::Constraint => {
+ if let Some(constraint) = current_constraint.as_mut() {
+ if let Some(rest) = trimmed.strip_prefix("desc:") {
+ let text = rest.trim().to_string();
+ if constraint.description.is_empty() {
+ constraint.description = text;
+ } else {
+ constraint.description.push(' ');
+ constraint.description.push_str(&text);
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("expr:") {
+ constraint.expression = Some(rest.trim().to_string());
+ } else {
+ // Continuation of description
+ if !constraint.description.is_empty() {
+ constraint.description.push(' ');
+ constraint.description.push_str(trimmed);
+ }
+ }
+ }
+ }
+ BlockContext::Lock => {
+ if let Some(lock) = current_lock.as_mut() {
+ if let Some(rest) = trimmed.strip_prefix("type:") {
+ lock.lock_type = self.parse_lock_type(rest.trim());
+ } else if let Some(rest) = trimmed.strip_prefix("scope:") {
+ lock.scope = match rest.trim() {
+ "internal" => super::KAPI_LOCK_INTERNAL,
+ "acquires" => super::KAPI_LOCK_ACQUIRES,
+ "releases" => super::KAPI_LOCK_RELEASES,
+ "caller_held" => super::KAPI_LOCK_CALLER_HELD,
+ _ => super::KAPI_LOCK_INTERNAL,
+ };
+ } else if let Some(rest) = trimmed.strip_prefix("desc:") {
+ let text = rest.trim().to_string();
+ if lock.description.is_empty() {
+ lock.description = text;
+ } else {
+ lock.description.push(' ');
+ lock.description.push_str(&text);
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("acquired:") {
+ // Same rule as kdoc_apispec.py: a lock that is both
+ // acquired and released stays KAPI_LOCK_INTERNAL.
+ if matches!(rest.trim().to_lowercase().as_str(), "true" | "yes") {
+ lock.scope = if lock.scope == super::KAPI_LOCK_RELEASES {
+ super::KAPI_LOCK_INTERNAL
+ } else {
+ super::KAPI_LOCK_ACQUIRES
+ };
+ }
+ } else if let Some(rest) = trimmed.strip_prefix("released:") {
+ if matches!(rest.trim().to_lowercase().as_str(), "true" | "yes") {
+ lock.scope = if lock.scope == super::KAPI_LOCK_ACQUIRES {
+ super::KAPI_LOCK_INTERNAL
+ } else {
+ super::KAPI_LOCK_RELEASES
+ };
+ }
+ } else {
+ // Continuation of description
+ if !lock.description.is_empty() {
+ lock.description.push(' ');
+ lock.description.push_str(trimmed);
+ }
+ }
+ }
+ }
+ BlockContext::Return => {
+ if let Some(ret) = current_return.as_mut() {
+ if let Some(rest) = trimmed.strip_prefix("type:") {
+ let raw = rest.trim();
+ ret.type_name = raw.to_string();
+ ret.return_type = self.parse_param_type(raw);
+ } else if let Some(rest) = trimmed.strip_prefix("check-type:") {
+ ret.check_type = self.parse_return_check_type(rest.trim());
+ } else if let Some(rest) = trimmed.strip_prefix("success:") {
+ (ret.success_value, ret.success_min, ret.success_max) =
+ parse_return_success(rest.trim());
+ } else if let Some(rest) = trimmed.strip_prefix("desc:") {
+ let text = rest.trim().to_string();
+ if ret.description.is_empty() {
+ ret.description = text;
+ } else {
+ ret.description.push(' ');
+ ret.description.push_str(&text);
+ }
+ } else {
+ // Continuation of description
+ if !ret.description.is_empty() {
+ ret.description.push(' ');
+ ret.description.push_str(trimmed);
+ }
+ }
+ }
+ }
+ BlockContext::StateTransition => {
+ if let Some(trans) = current_state_trans.as_mut() {
+ if let Some(rest) = trimmed.strip_prefix("object:") {
+ trans.object = rest.trim().to_string();
+ } else if let Some(rest) = trimmed.strip_prefix("from:") {
+ trans.from_state = rest.trim().to_string();
+ } else if let Some(rest) = trimmed.strip_prefix("to:") {
+ trans.to_state = rest.trim().to_string();
+ } else if let Some(rest) = trimmed.strip_prefix("condition:") {
+ trans.condition = Some(rest.trim().to_string());
+ } else if let Some(rest) = trimmed.strip_prefix("desc:") {
+ trans.description = rest.trim().to_string();
+ }
+ }
+ }
+ BlockContext::None => {}
+ }
+ }
+
+ /// Flush the current block, pushing items into the spec
+ #[allow(clippy::too_many_arguments)]
+ fn flush_block(
+ &self,
+ block: &mut BlockContext,
+ spec: &mut ApiSpec,
+ current_error: &mut Option<ErrorSpec>,
+ current_signal: &mut Option<SignalSpec>,
+ current_capability: &mut Option<CapabilitySpec>,
+ current_side_effect: &mut Option<SideEffectSpec>,
+ current_constraint: &mut Option<ConstraintSpec>,
+ current_lock: &mut Option<LockSpec>,
+ current_return: &mut Option<ReturnSpec>,
+ current_state_trans: &mut Option<StateTransitionSpec>,
+ ) {
+ match block {
+ BlockContext::Error(_) => {
+ if let Some(error) = current_error.take() {
+ spec.errors.push(error);
+ }
+ }
+ BlockContext::Signal => {
+ if let Some(signal) = current_signal.take() {
+ spec.signals.push(signal);
+ }
+ }
+ BlockContext::Capability => {
+ if let Some(cap) = current_capability.take() {
+ spec.capabilities.push(cap);
+ }
+ }
+ BlockContext::SideEffect => {
+ if let Some(effect) = current_side_effect.take() {
+ spec.side_effects.push(effect);
+ }
+ }
+ BlockContext::Constraint => {
+ if let Some(constraint) = current_constraint.take() {
+ spec.constraints.push(constraint);
+ }
+ }
+ BlockContext::Lock => {
+ if let Some(lock) = current_lock.take() {
+ spec.locks.push(lock);
+ }
+ }
+ BlockContext::Return => {
+ if let Some(mut ret) = current_return.take() {
+ ret.keep_used_success_fields();
+ spec.return_spec = Some(ret);
+ }
+ }
+ BlockContext::StateTransition => {
+ if let Some(trans) = current_state_trans.take() {
+ spec.state_transitions.push(trans);
+ }
+ }
+ _ => {}
+ }
+ *block = BlockContext::None;
+ }
+
+ /// Extract parameter type names from SYSCALL_DEFINE signature
+ fn extract_types_from_signature(&self, sig: &str) -> HashMap<String, String> {
+ let mut types = HashMap::new();
+
+ // Find content between outermost parens
+ let content = if let Some(start) = sig.find('(') {
+ let end = sig.rfind(')').unwrap_or(sig.len());
+ &sig[start + 1..end]
+ } else {
+ return types;
+ };
+
+ // Split by comma and process type/name pairs
+ // SYSCALL_DEFINE format: (syscall_name, type1, name1, type2, name2, ...)
+ let parts: Vec<&str> = content.split(',').map(|s| s.trim()).collect();
+
+ // Skip first part (syscall name), then process pairs
+ let mut i = 1;
+ while i + 1 < parts.len() {
+ let type_part = parts[i].trim();
+ let name_part = parts[i + 1].trim();
+
+ // Build the type_name string: "type name"
+ let type_name = format!("{} {}", type_part, name_part);
+ types.insert(name_part.to_string(), type_name);
+
+ i += 2;
+ }
+
+ types
+ }
+
+ /// Collect the raw lines of a free-form section: the text after the
+ /// key plus every following indented or blank line, up to the next
+ /// annotation line.
+ fn collect_section<'a>(
+ &self,
+ lines: &[&'a str],
+ start_idx: usize,
+ first_part: &'a str,
+ ) -> (Vec<&'a str>, usize) {
+ let mut section = vec![first_part];
+ let mut i = start_idx + 1;
+
+ while i < lines.len() {
+ let line = lines[i];
+ if self.is_annotation_line(line) {
+ break;
+ }
+ if !line.trim().is_empty() && !is_indented_line(line) {
+ break;
+ }
+ section.push(line);
+ i += 1;
+ }
+
+ (section, i)
+ }
+
+ fn is_annotation_line(&self, line: &str) -> bool {
+ let trimmed = line.trim_start();
+ if !trimmed.contains(':') {
+ return false;
+ }
+ let annotations = [
+ "param:",
+ "param-count:",
+ "error:",
+ "lock:",
+ "signal:",
+ "side-effect:",
+ "state-trans:",
+ "capability:",
+ "constraint:",
+ "return:",
+ "examples:",
+ "notes:",
+ "context-",
+ "long-desc:",
+ "api-type:",
+ ];
+
+ for ann in &annotations {
+ if trimmed.starts_with(ann) {
+ return true;
+ }
+ }
+ false
+ }
+
+ /// Parse a constraint expression and apply it to `param`.
+ /// Shapes:
+ /// NAME (e.g. "user_path", "nonzero")
+ /// NAME ( ARG (, ARG)* ) (e.g. "range(0, 4096)", "buffer(2)")
+ /// Returns true if the expression matched a known constraint kind,
+ /// populating `param`'s numeric fields. Returns false if the text
+ /// is free-form, leaving `param` untouched.
+ fn apply_constraint_expr(&self, param: &mut ParamSpec, text: &str) -> bool {
+ let t = text.trim();
+ if t.is_empty() {
+ return false;
+ }
+ // Split NAME ( ARGS ); no nesting, no escaping.
+ let (name, args): (&str, Option<&str>) = match (t.find('('), t.rfind(')')) {
+ (Some(lp), Some(rp)) if rp > lp => (t[..lp].trim(), Some(t[lp + 1..rp].trim())),
+ _ => (t, None),
+ };
+ // Bail out on anything that looks like free text (spaces inside the
+ // name part).
+ if name.contains(char::is_whitespace) || name.is_empty() {
+ return false;
+ }
+ let name_lc = name.to_ascii_lowercase();
+ let split_args = || -> Vec<String> {
+ args.map(|a| a.split(',').map(|s| s.trim().to_string()).collect())
+ .unwrap_or_default()
+ };
+ match name_lc.as_str() {
+ "range" => {
+ let a = split_args();
+ if a.len() != 2 {
+ return false;
+ }
+ param.min_value = parse_i64_literal(&a[0]);
+ param.max_value = parse_i64_literal(&a[1]);
+ param.constraint_type = 1; // KAPI_CONSTRAINT_RANGE
+ true
+ }
+ "mask" => {
+ let a = split_args();
+ if a.len() != 1 {
+ return false;
+ }
+ // Symbolic masks (e.g. "O_RDONLY | O_WRONLY | ...") can't
+ // be resolved at parse time; leave valid_mask as None so
+ // downstream consumers treat the mask as unknown, matching
+ // the long-form `valid-mask:` handler (which also leaves
+ // the slot untouched when the value isn't a literal).
+ param.valid_mask = parse_u64_literal(&a[0]);
+ param.constraint_type = 2; // KAPI_CONSTRAINT_MASK
+ true
+ }
+ "enum" => {
+ let a = split_args();
+ if a.is_empty() {
+ return false;
+ }
+ // --vmlinux and --debugfs report each value in decimal, so
+ // numeric literals are normalised; symbolic names stay.
+ param.enum_values = a
+ .into_iter()
+ .map(|v| parse_i64_literal(&v).map_or(v, |n| n.to_string()))
+ .collect();
+ param.constraint_type = 3; // KAPI_CONSTRAINT_ENUM
+ true
+ }
+ "alignment" | "align" => {
+ let a = split_args();
+ if a.len() != 1 {
+ return false;
+ }
+ param.alignment = parse_u64_literal(&a[0]).and_then(|n| u32::try_from(n).ok());
+ param.constraint_type = 4; // KAPI_CONSTRAINT_ALIGNMENT
+ true
+ }
+ "power_of_two" => {
+ if args.is_some() {
+ return false;
+ }
+ param.constraint_type = 5; // KAPI_CONSTRAINT_POWER_OF_TWO
+ true
+ }
+ "page_aligned" => {
+ if args.is_some() {
+ return false;
+ }
+ param.constraint_type = 6; // KAPI_CONSTRAINT_PAGE_ALIGNED
+ true
+ }
+ "nonzero" => {
+ if args.is_some() {
+ return false;
+ }
+ param.constraint_type = 7; // KAPI_CONSTRAINT_NONZERO
+ true
+ }
+ "user_string" => {
+ // Optional size argument: user_string(N)
+ if let Some(arg) = args {
+ if let Some(n) = parse_u64_literal(arg).and_then(|n| u32::try_from(n).ok()) {
+ param.size = Some(n);
+ }
+ }
+ param.constraint_type = 8; // KAPI_CONSTRAINT_USER_STRING
+ true
+ }
+ "user_path" => {
+ if args.is_some() {
+ return false;
+ }
+ param.constraint_type = 9; // KAPI_CONSTRAINT_USER_PATH
+ true
+ }
+ "user_ptr" => {
+ if args.is_some() {
+ return false;
+ }
+ param.constraint_type = 10; // KAPI_CONSTRAINT_USER_PTR
+ true
+ }
+ "buffer" => {
+ // buffer(size_param_idx): capture the index into
+ // param.size_param_idx so it matches the long-form
+ // `size-param: N` handler below (and the C struct
+ // field populated by KAPI_PARAM_SIZE_PARAM()).
+ let a = split_args();
+ if a.len() != 1 {
+ return false;
+ }
+ param.size_param_idx = a[0].parse().ok();
+ param.constraint_type = 11; // KAPI_CONSTRAINT_BUFFER
+ true
+ }
+ "custom" => {
+ // custom(fn_name): record function name as free-text constraint
+ // so downstream tooling can wire it up.
+ if let Some(arg) = args {
+ param.constraint = Some(arg.trim().to_string());
+ }
+ param.constraint_type = 12; // KAPI_CONSTRAINT_CUSTOM
+ true
+ }
+ _ => false,
+ }
+ }
+
+ fn parse_context_flags(&self, flags: &str) -> Vec<String> {
+ flags
+ .split('|')
+ .map(|f| self.ctx_alias(f.trim()).to_string())
+ .filter(|f| !f.is_empty())
+ .collect()
+ }
+
+ /// Parse a comma-separated short-form context list
+ /// (e.g. "process, sleepable" -> ["KAPI_CTX_PROCESS", "KAPI_CTX_SLEEPABLE"]).
+ /// Tokens that already look like KAPI_CTX_* are passed through.
+ fn parse_context_list(&self, flags: &str) -> Vec<String> {
+ flags
+ .split(',')
+ .map(|f| self.ctx_alias(f.trim()).to_string())
+ .filter(|f| !f.is_empty())
+ .collect()
+ }
+
+ /// Canonicalise a single context token to its KAPI_CTX_* spelling.
+ /// Short aliases are case-insensitive. Unknown tokens pass through
+ /// verbatim so mixed/long-form input keeps working.
+ fn ctx_alias(&self, tok: &str) -> String {
+ let t = tok.trim();
+ if t.is_empty() {
+ return String::new();
+ }
+ match t.to_ascii_lowercase().as_str() {
+ "process" => "KAPI_CTX_PROCESS".to_string(),
+ "softirq" => "KAPI_CTX_SOFTIRQ".to_string(),
+ "hardirq" => "KAPI_CTX_HARDIRQ".to_string(),
+ "nmi" => "KAPI_CTX_NMI".to_string(),
+ "atomic" => "KAPI_CTX_ATOMIC".to_string(),
+ "sleepable" => "KAPI_CTX_SLEEPABLE".to_string(),
+ "preempt_disabled" => "KAPI_CTX_PREEMPT_DISABLED".to_string(),
+ "irq_disabled" => "KAPI_CTX_IRQ_DISABLED".to_string(),
+ _ => t.to_string(),
+ }
+ }
+
+ fn error_name_to_code(&self, name: &str) -> i32 {
+ match name {
+ "EPERM" => -1,
+ "ENOENT" => -2,
+ "ESRCH" => -3,
+ "EINTR" => -4,
+ "EIO" => -5,
+ "ENXIO" => -6,
+ "E2BIG" => -7,
+ "ENOEXEC" => -8,
+ "EBADF" => -9,
+ "ECHILD" => -10,
+ "EAGAIN" | "EWOULDBLOCK" => -11,
+ "ENOMEM" => -12,
+ "EACCES" => -13,
+ "EFAULT" => -14,
+ "ENOTBLK" => -15,
+ "EBUSY" => -16,
+ "EEXIST" => -17,
+ "EXDEV" => -18,
+ "ENODEV" => -19,
+ "ENOTDIR" => -20,
+ "EISDIR" => -21,
+ "EINVAL" => -22,
+ "ENFILE" => -23,
+ "EMFILE" => -24,
+ "ENOTTY" => -25,
+ "ETXTBSY" => -26,
+ "EFBIG" => -27,
+ "ENOSPC" => -28,
+ "ESPIPE" => -29,
+ "EROFS" => -30,
+ "EMLINK" => -31,
+ "EPIPE" => -32,
+ "EDOM" => -33,
+ "ERANGE" => -34,
+ "EDEADLK" => -35,
+ "ENAMETOOLONG" => -36,
+ "ENOLCK" => -37,
+ "ENOSYS" => -38,
+ "ENOTEMPTY" => -39,
+ "ELOOP" => -40,
+ "ENOMSG" => -42,
+ "ENODATA" => -61,
+ "ENOLINK" => -67,
+ "EPROTO" => -71,
+ "EOVERFLOW" => -75,
+ "ELIBBAD" => -80,
+ "EILSEQ" => -84,
+ "ENOTSOCK" => -88,
+ "EDESTADDRREQ" => -89,
+ "EMSGSIZE" => -90,
+ "EPROTOTYPE" => -91,
+ "ENOPROTOOPT" => -92,
+ "EPROTONOSUPPORT" => -93,
+ "EOPNOTSUPP" | "ENOTSUP" => -95,
+ "EADDRINUSE" => -98,
+ "EADDRNOTAVAIL" => -99,
+ "ENETDOWN" => -100,
+ "ENETUNREACH" => -101,
+ "ENETRESET" => -102,
+ "ECONNABORTED" => -103,
+ "ECONNRESET" => -104,
+ "ENOBUFS" => -105,
+ "EISCONN" => -106,
+ "ENOTCONN" => -107,
+ "ETIMEDOUT" => -110,
+ "ECONNREFUSED" => -111,
+ "EALREADY" => -114,
+ "EINPROGRESS" => -115,
+ "ESTALE" => -116,
+ "EDQUOT" => -122,
+ "ENOMEDIUM" => -123,
+ "ENOKEY" => -126,
+ "EHWPOISON" => -133,
+ "ERESTARTSYS" => -512,
+ _ => 0,
+ }
+ }
+
+ /// Map a KAPI_TYPE_* token (or its short-form alias) to the numeric
+ /// value declared in `enum kapi_param_type` in
+ /// `include/linux/kernel_api_spec.h`.
+ fn parse_param_type(&self, type_str: &str) -> u32 {
+ let s = type_str.trim();
+ match s {
+ "KAPI_TYPE_VOID" => 0,
+ "KAPI_TYPE_INT" => 1,
+ "KAPI_TYPE_UINT" => 2,
+ "KAPI_TYPE_PTR" => 3,
+ "KAPI_TYPE_STRUCT" => 4,
+ "KAPI_TYPE_UNION" => 5,
+ "KAPI_TYPE_ENUM" => 6,
+ "KAPI_TYPE_FUNC_PTR" => 7,
+ "KAPI_TYPE_ARRAY" => 8,
+ "KAPI_TYPE_FD" => 9,
+ "KAPI_TYPE_USER_PTR" => 10,
+ "KAPI_TYPE_PATH" => 11,
+ "KAPI_TYPE_CUSTOM" => 12,
+ _ => match s.to_ascii_lowercase().as_str() {
+ "void" => 0,
+ "int" => 1,
+ "uint" => 2,
+ "ptr" => 3,
+ "struct" => 4,
+ "union" => 5,
+ "enum" => 6,
+ "func_ptr" => 7,
+ "array" => 8,
+ "fd" => 9,
+ "user_ptr" | "uptr" => 10,
+ "path" => 11,
+ "custom" => 12,
+ _ => 0,
+ },
+ }
+ }
+
+ /// Map a KAPI_CONSTRAINT_* token to the numeric value declared in
+ /// `enum kapi_constraint_type` in `include/linux/kernel_api_spec.h`.
+ fn parse_constraint_type(&self, type_str: &str) -> u32 {
+ let s = type_str.trim();
+ match s {
+ "KAPI_CONSTRAINT_NONE" => 0,
+ "KAPI_CONSTRAINT_RANGE" => 1,
+ "KAPI_CONSTRAINT_MASK" => 2,
+ "KAPI_CONSTRAINT_ENUM" => 3,
+ "KAPI_CONSTRAINT_ALIGNMENT" => 4,
+ "KAPI_CONSTRAINT_POWER_OF_TWO" => 5,
+ "KAPI_CONSTRAINT_PAGE_ALIGNED" => 6,
+ "KAPI_CONSTRAINT_NONZERO" => 7,
+ "KAPI_CONSTRAINT_USER_STRING" => 8,
+ "KAPI_CONSTRAINT_USER_PATH" => 9,
+ "KAPI_CONSTRAINT_USER_PTR" => 10,
+ "KAPI_CONSTRAINT_BUFFER" => 11,
+ "KAPI_CONSTRAINT_CUSTOM" => 12,
+ _ => 0,
+ }
+ }
+
+ fn parse_param_flags(&self, flags: &str) -> u32 {
+ flags
+ .split('|')
+ .map(|f| self.parse_param_flag_token(f.trim()))
+ .fold(0, |acc, bit| acc | bit)
+ }
+
+ /// Parse one flag token (long or short form, case-insensitive for
+ /// short form). Returns 0 for unknown tokens.
+ fn parse_param_flag_token(&self, tok: &str) -> u32 {
+ let t = tok.trim();
+ // KAPI_PARAM_* names and upper-case short forms first.
+ match t {
+ "KAPI_PARAM_IN" | "IN" => return 1,
+ "KAPI_PARAM_OUT" | "OUT" => return 2,
+ "KAPI_PARAM_INOUT" | "INOUT" => return 3,
+ "KAPI_PARAM_OPTIONAL" | "OPTIONAL" => return 1 << 3,
+ "KAPI_PARAM_CONST" | "CONST" => return 1 << 4,
+ "KAPI_PARAM_VOLATILE" | "VOLATILE" => return 1 << 5,
+ "KAPI_PARAM_USER" | "USER" => return 1 << 6,
+ "KAPI_PARAM_DMA" | "DMA" => return 1 << 7,
+ "KAPI_PARAM_ALIGNED" | "ALIGNED" => return 1 << 8,
+ _ => {}
+ }
+ // English short aliases (case-insensitive).
+ match t.to_ascii_lowercase().as_str() {
+ "input" => 1,
+ "output" => 2,
+ "inout" => 3,
+ "optional" => 1 << 3,
+ "const" => 1 << 4,
+ "volatile" => 1 << 5,
+ "user" => 1 << 6,
+ "dma" => 1 << 7,
+ "aligned" => 1 << 8,
+ _ => 0,
+ }
+ }
+
+ /// Map a KAPI_LOCK_* token to the numeric value declared in
+ /// `enum kapi_lock_type` in `include/linux/kernel_api_spec.h`.
+ fn parse_lock_type(&self, type_str: &str) -> u32 {
+ let s = type_str.trim();
+ match s {
+ "KAPI_LOCK_NONE" => 0,
+ "KAPI_LOCK_MUTEX" => 1,
+ "KAPI_LOCK_SPINLOCK" => 2,
+ "KAPI_LOCK_RWLOCK" => 3,
+ "KAPI_LOCK_SEQLOCK" => 4,
+ "KAPI_LOCK_RCU" => 5,
+ "KAPI_LOCK_SEMAPHORE" => 6,
+ "KAPI_LOCK_CUSTOM" => 7,
+ _ => match s.to_ascii_lowercase().as_str() {
+ "none" => 0,
+ "mutex" => 1,
+ "spinlock" => 2,
+ "rwlock" => 3,
+ "seqlock" => 4,
+ "rcu" => 5,
+ "semaphore" => 6,
+ "custom" => 7,
+ _ => 0,
+ },
+ }
+ }
+
+ fn parse_signal_direction(&self, dir: &str) -> u32 {
+ let s = dir.trim();
+ match s {
+ "KAPI_SIGNAL_RECEIVE" => 1,
+ "KAPI_SIGNAL_SEND" => 2,
+ "KAPI_SIGNAL_HANDLE" => 4,
+ "KAPI_SIGNAL_BLOCK" => 8,
+ "KAPI_SIGNAL_IGNORE" => 16,
+ _ => match s.to_ascii_lowercase().as_str() {
+ "receive" => 1,
+ "send" => 2,
+ "handle" => 4,
+ "block" => 8,
+ "ignore" => 16,
+ _ => 0,
+ },
+ }
+ }
+
+ fn parse_signal_action(&self, action: &str) -> u32 {
+ let s = action.trim();
+ match s {
+ "KAPI_SIGNAL_ACTION_DEFAULT" => 0,
+ "KAPI_SIGNAL_ACTION_TERMINATE" => 1,
+ "KAPI_SIGNAL_ACTION_COREDUMP" => 2,
+ "KAPI_SIGNAL_ACTION_STOP" => 3,
+ "KAPI_SIGNAL_ACTION_CONTINUE" => 4,
+ "KAPI_SIGNAL_ACTION_CUSTOM" => 5,
+ "KAPI_SIGNAL_ACTION_RETURN" => 6,
+ "KAPI_SIGNAL_ACTION_RESTART" => 7,
+ "KAPI_SIGNAL_ACTION_QUEUE" => 8,
+ "KAPI_SIGNAL_ACTION_DISCARD" => 9,
+ "KAPI_SIGNAL_ACTION_TRANSFORM" => 10,
+ _ => match s.to_ascii_lowercase().as_str() {
+ "default" => 0,
+ "terminate" => 1,
+ "coredump" => 2,
+ "stop" => 3,
+ "continue" => 4,
+ "custom" => 5,
+ "return" => 6,
+ "restart" => 7,
+ "queue" => 8,
+ "discard" => 9,
+ "transform" => 10,
+ _ => 0,
+ },
+ }
+ }
+
+ fn parse_signal_timing(&self, timing: &str) -> u32 {
+ let s = timing.trim();
+ match s {
+ "KAPI_SIGNAL_TIME_BEFORE" => 0,
+ "KAPI_SIGNAL_TIME_DURING" => 1,
+ "KAPI_SIGNAL_TIME_AFTER" => 2,
+ _ => match s.to_ascii_lowercase().as_str() {
+ "before" => 0,
+ "during" => 1,
+ "after" => 2,
+ _ => 0,
+ },
+ }
+ }
+
+ /// Accept a hex literal ("0x4"), a decimal literal ("4"), or a '|'-separated
+ /// bitmask expression. Unknown tokens contribute 0.
+ fn parse_hex_or_bitmask(&self, value: &str) -> u32 {
+ let v = value.trim();
+ if let Some(hex) = v.strip_prefix("0x").or_else(|| v.strip_prefix("0X")) {
+ if let Ok(n) = u32::from_str_radix(hex, 16) {
+ return n;
+ }
+ }
+ if let Ok(n) = v.parse::<u32>() {
+ return n;
+ }
+ let mut acc = 0u32;
+ for part in v.split(['|', ',']) {
+ let t = part.trim();
+ if t.is_empty() {
+ continue;
+ }
+ if let Some(hex) = t.strip_prefix("0x").or_else(|| t.strip_prefix("0X")) {
+ if let Ok(n) = u32::from_str_radix(hex, 16) {
+ acc |= n;
+ continue;
+ }
+ }
+ if let Ok(n) = t.parse::<u32>() {
+ acc |= n;
+ }
+ }
+ acc
+ }
+
+ /// Parse a '|'-separated list of KAPI_SIGNAL_STATE_* tokens (or short
+ /// names like "RUNNING") and OR their bit values together. Matches the
+ /// BIT(N) definitions in kernel_api_spec.h.
+ fn parse_signal_state_mask(&self, value: &str) -> u32 {
+ let mut acc = 0u32;
+ for part in value.split(['|', ',']) {
+ let t = part.trim().trim_start_matches("KAPI_SIGNAL_STATE_");
+ let bit = match t.to_ascii_uppercase().as_str() {
+ "RUNNING" => 1 << 0,
+ "SLEEPING" => 1 << 1,
+ "STOPPED" => 1 << 2,
+ "TRACED" => 1 << 3,
+ "ZOMBIE" => 1 << 4,
+ "DEAD" => 1 << 5,
+ _ => 0,
+ };
+ acc |= bit;
+ }
+ acc
+ }
+
+ /// Bitmask of `KAPI_EFFECT_*` values joined by '|' or ','.
+ /// Values match `enum kapi_side_effect_type` in
+ /// `include/linux/kernel_api_spec.h`.
+ fn parse_effect_type(&self, type_str: &str) -> u32 {
+ let sep = if type_str.contains('|') || !type_str.contains(',') {
+ '|'
+ } else {
+ ','
+ };
+ let mut result = 0;
+ for flag in type_str.split(sep) {
+ let t = flag.trim();
+ let bit = match t {
+ "KAPI_EFFECT_NONE" => 0,
+ "KAPI_EFFECT_ALLOC_MEMORY" => 1 << 0,
+ "KAPI_EFFECT_FREE_MEMORY" => 1 << 1,
+ "KAPI_EFFECT_MODIFY_STATE" => 1 << 2,
+ "KAPI_EFFECT_SIGNAL_SEND" => 1 << 3,
+ "KAPI_EFFECT_FILE_POSITION" => 1 << 4,
+ "KAPI_EFFECT_LOCK_ACQUIRE" => 1 << 5,
+ "KAPI_EFFECT_LOCK_RELEASE" => 1 << 6,
+ "KAPI_EFFECT_RESOURCE_CREATE" => 1 << 7,
+ "KAPI_EFFECT_RESOURCE_DESTROY" => 1 << 8,
+ "KAPI_EFFECT_SCHEDULE" => 1 << 9,
+ "KAPI_EFFECT_HARDWARE" => 1 << 10,
+ "KAPI_EFFECT_NETWORK" => 1 << 11,
+ "KAPI_EFFECT_FILESYSTEM" => 1 << 12,
+ "KAPI_EFFECT_PROCESS_STATE" => 1 << 13,
+ "KAPI_EFFECT_IRREVERSIBLE" => 1 << 14,
+ _ => match t.to_ascii_lowercase().as_str() {
+ "none" => 0,
+ "alloc_memory" => 1 << 0,
+ "free_memory" => 1 << 1,
+ "modify_state" => 1 << 2,
+ "signal_send" => 1 << 3,
+ "file_position" => 1 << 4,
+ "lock_acquire" => 1 << 5,
+ "lock_release" => 1 << 6,
+ "resource_create" => 1 << 7,
+ "resource_destroy" => 1 << 8,
+ "schedule" => 1 << 9,
+ "hardware" => 1 << 10,
+ "network" => 1 << 11,
+ "filesystem" => 1 << 12,
+ "process_state" => 1 << 13,
+ "irreversible" => 1 << 14,
+ _ => 0,
+ },
+ };
+ result |= bit;
+ }
+ result
+ }
+
+ fn parse_capability_value(&self, cap: &str) -> i32 {
+ match cap {
+ "CAP_CHOWN" => 0,
+ "CAP_DAC_OVERRIDE" => 1,
+ "CAP_DAC_READ_SEARCH" => 2,
+ "CAP_FOWNER" => 3,
+ "CAP_FSETID" => 4,
+ "CAP_KILL" => 5,
+ "CAP_SETGID" => 6,
+ "CAP_SETUID" => 7,
+ "CAP_SETPCAP" => 8,
+ "CAP_LINUX_IMMUTABLE" => 9,
+ "CAP_NET_BIND_SERVICE" => 10,
+ "CAP_NET_BROADCAST" => 11,
+ "CAP_NET_ADMIN" => 12,
+ "CAP_NET_RAW" => 13,
+ "CAP_IPC_LOCK" => 14,
+ "CAP_IPC_OWNER" => 15,
+ "CAP_SYS_MODULE" => 16,
+ "CAP_SYS_RAWIO" => 17,
+ "CAP_SYS_CHROOT" => 18,
+ "CAP_SYS_PTRACE" => 19,
+ "CAP_SYS_PACCT" => 20,
+ "CAP_SYS_ADMIN" => 21,
+ "CAP_SYS_BOOT" => 22,
+ "CAP_SYS_NICE" => 23,
+ "CAP_SYS_RESOURCE" => 24,
+ "CAP_SYS_TIME" => 25,
+ "CAP_SYS_TTY_CONFIG" => 26,
+ "CAP_MKNOD" => 27,
+ "CAP_LEASE" => 28,
+ "CAP_AUDIT_WRITE" => 29,
+ "CAP_AUDIT_CONTROL" => 30,
+ "CAP_SETFCAP" => 31,
+ "CAP_MAC_OVERRIDE" => 32,
+ "CAP_MAC_ADMIN" => 33,
+ "CAP_SYSLOG" => 34,
+ "CAP_WAKE_ALARM" => 35,
+ "CAP_BLOCK_SUSPEND" => 36,
+ "CAP_AUDIT_READ" => 37,
+ "CAP_PERFMON" => 38,
+ "CAP_BPF" => 39,
+ "CAP_CHECKPOINT_RESTORE" => 40,
+ _ => 0,
+ }
+ }
+
+ /// Map a KAPI_RETURN_* token to the numeric value declared in
+ /// `enum kapi_return_check_type` in `include/linux/kernel_api_spec.h`.
+ fn parse_return_check_type(&self, check: &str) -> u32 {
+ let s = check.trim();
+ match s {
+ "KAPI_RETURN_EXACT" => 0,
+ "KAPI_RETURN_RANGE" => 1,
+ "KAPI_RETURN_ERROR_CHECK" => 2,
+ "KAPI_RETURN_FD" => 3,
+ "KAPI_RETURN_CUSTOM" => 4,
+ "KAPI_RETURN_NO_RETURN" => 5,
+ _ => match s.to_ascii_lowercase().as_str() {
+ "exact" => 0,
+ "range" => 1,
+ "error_check" => 2,
+ "fd" => 3,
+ "custom" => 4,
+ "no_return" => 5,
+ _ => 0,
+ },
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn parser() -> KerneldocParser {
+ KerneldocParser::new()
+ }
+
+ #[test]
+ fn parse_minimal_kerneldoc() {
+ let doc = "\
+sys_foo - Do something useful
+context-flags: KAPI_CTX_PROCESS
+param-count: 1
+@fd: The file descriptor
+error: EBADF, Bad file descriptor
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_foo", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.name, "sys_foo");
+ assert_eq!(spec.api_type, "syscall");
+ assert_eq!(spec.description.as_deref(), Some("Do something useful"));
+ assert_eq!(spec.param_count, Some(1));
+ assert_eq!(spec.parameters.len(), 1);
+ assert_eq!(spec.parameters[0].name, "fd");
+ assert_eq!(spec.parameters[0].description, "The file descriptor");
+ assert_eq!(spec.errors.len(), 1);
+ assert_eq!(spec.errors[0].name, "EBADF");
+ assert_eq!(spec.errors[0].error_code, -9);
+ }
+
+ #[test]
+ fn parse_multiple_param_types() {
+ let doc = "\
+sys_bar - Multiple params
+@fd: file descriptor arg
+@buf: user buffer
+@count: byte count
+@flags: option flags
+param: fd
+ type: KAPI_TYPE_FD
+param: buf
+ type: KAPI_TYPE_USER_PTR
+param: count
+ type: KAPI_TYPE_UINT
+param: flags
+ type: KAPI_TYPE_UINT
+";
+ let sig = "(bar, int, fd, char __user *, buf, size_t, count, unsigned long, flags)";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_bar", "syscall", Some(sig))
+ .unwrap();
+
+ assert_eq!(spec.parameters.len(), 4);
+
+ let fd_param = spec.parameters.iter().find(|p| p.name == "fd").unwrap();
+ assert_eq!(fd_param.param_type, 9); // FD (kernel enum)
+
+ let buf_param = spec.parameters.iter().find(|p| p.name == "buf").unwrap();
+ assert_eq!(buf_param.param_type, 10); // USER_PTR (kernel enum)
+ assert_eq!(buf_param.type_name, "char __user * buf");
+
+ let count_param = spec.parameters.iter().find(|p| p.name == "count").unwrap();
+ assert_eq!(count_param.param_type, 2); // UINT
+
+ let flags_param = spec.parameters.iter().find(|p| p.name == "flags").unwrap();
+ assert_eq!(flags_param.param_type, 2); // UINT
+ }
+
+ #[test]
+ fn parse_error_codes_with_descriptions() {
+ let doc = "\
+sys_err - Error test
+error: EBADF
+ desc: Bad file descriptor
+ condition: fd < 0
+error: EFAULT
+ desc: Bad user pointer
+ condition: buf is NULL
+error: EINVAL
+ desc: Invalid argument
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_err", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.errors.len(), 3);
+
+ assert_eq!(spec.errors[0].name, "EBADF");
+ assert_eq!(spec.errors[0].error_code, -9);
+ assert_eq!(spec.errors[0].description, "Bad file descriptor");
+ assert_eq!(spec.errors[0].condition, "fd < 0");
+
+ assert_eq!(spec.errors[1].name, "EFAULT");
+ assert_eq!(spec.errors[1].error_code, -14);
+ assert_eq!(spec.errors[1].description, "Bad user pointer");
+
+ assert_eq!(spec.errors[2].name, "EINVAL");
+ assert_eq!(spec.errors[2].error_code, -22);
+ assert_eq!(spec.errors[2].description, "Invalid argument");
+ }
+
+ #[test]
+ fn parse_context_flags() {
+ let doc = "\
+sys_ctx - Context test
+context-flags: KAPI_CTX_PROCESS|KAPI_CTX_SLEEPABLE
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_ctx", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.context_flags.len(), 2);
+ assert_eq!(spec.context_flags[0], "KAPI_CTX_PROCESS");
+ assert_eq!(spec.context_flags[1], "KAPI_CTX_SLEEPABLE");
+ }
+
+ #[test]
+ fn parse_context_list_short() {
+ // "contexts: process, sleepable" -> KAPI_CTX_PROCESS | SLEEPABLE
+ let doc = "\
+sys_ctx - Context test
+contexts: process, sleepable
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_ctx", "syscall", None)
+ .unwrap();
+
+ assert_eq!(
+ spec.context_flags,
+ vec![
+ "KAPI_CTX_PROCESS".to_string(),
+ "KAPI_CTX_SLEEPABLE".to_string(),
+ ]
+ );
+ }
+
+ #[test]
+ fn parse_context_list_mixed() {
+ // Short tokens intermixed with explicit KAPI_CTX_* still work.
+ let doc = "\
+sys_ctx - Context test
+contexts: process, KAPI_CTX_SLEEPABLE, softirq
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_ctx", "syscall", None)
+ .unwrap();
+
+ assert_eq!(
+ spec.context_flags,
+ vec![
+ "KAPI_CTX_PROCESS".to_string(),
+ "KAPI_CTX_SLEEPABLE".to_string(),
+ "KAPI_CTX_SOFTIRQ".to_string(),
+ ]
+ );
+ }
+
+ #[test]
+ fn parse_context_flags_long_with_short_token() {
+ // Long-form "context-flags:" accepts "|"-joined short aliases.
+ let doc = "\
+sys_ctx - Context test
+context-flags: process | KAPI_CTX_SLEEPABLE
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_ctx", "syscall", None)
+ .unwrap();
+
+ assert_eq!(
+ spec.context_flags,
+ vec![
+ "KAPI_CTX_PROCESS".to_string(),
+ "KAPI_CTX_SLEEPABLE".to_string(),
+ ]
+ );
+ }
+
+ #[test]
+ fn parse_param_type_short_combined() {
+ // "type: uint, input" combines the type and flag aliases.
+ let doc = "\
+sys_t - Short type test
+param: size
+ type: uint, input
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_t", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.parameters.len(), 1);
+ assert_eq!(spec.parameters[0].param_type, 2); // KAPI_TYPE_UINT
+ assert_eq!(spec.parameters[0].flags, 1); // KAPI_PARAM_IN
+ }
+
+ #[test]
+ fn parse_param_type_short_multi_flag() {
+ // "type: path, input, user" sets both the IN and USER flags.
+ let doc = "\
+sys_t - Short type test
+param: filename
+ type: path, input, user
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_t", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.parameters.len(), 1);
+ assert_eq!(spec.parameters[0].param_type, 11); // PATH (kernel enum)
+ assert_eq!(spec.parameters[0].flags, 1 | (1 << 6)); // IN | USER
+ }
+
+ #[test]
+ fn parse_constraint_type_range_expr() {
+ // Short form: "constraint-type: range(0, 4096)" replaces the
+ // two-line long form "constraint-type: KAPI_CONSTRAINT_RANGE"
+ // + "range: 0, 4096".
+ let doc = "\
+sys_c - Constraint test
+param: count
+ type: uint, input
+ constraint-type: range(0, 4096)
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_c", "syscall", None)
+ .unwrap();
+
+ let p = &spec.parameters[0];
+ assert_eq!(p.constraint_type, 1); // KAPI_CONSTRAINT_RANGE
+ assert_eq!(p.min_value, Some(0));
+ assert_eq!(p.max_value, Some(4096));
+ }
+
+ #[test]
+ fn parse_constraint_type_mask_expr() {
+ let doc = "\
+sys_c - Constraint test
+param: flags
+ type: uint, input
+ constraint-type: mask(0xff)
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_c", "syscall", None)
+ .unwrap();
+
+ let p = &spec.parameters[0];
+ assert_eq!(p.constraint_type, 2); // KAPI_CONSTRAINT_MASK
+ assert_eq!(p.valid_mask, Some(0xff));
+ }
+
+ #[test]
+ fn parse_constraint_type_enum_expr() {
+ let doc = "\
+sys_c - Constraint test
+param: mode
+ type: int, input
+ constraint-type: enum(0, 0x10, -3, MODE_FAST)
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_c", "syscall", None)
+ .unwrap();
+
+ let p = &spec.parameters[0];
+ assert_eq!(p.constraint_type, 3); // KAPI_CONSTRAINT_ENUM
+ assert_eq!(p.enum_values, ["0", "16", "-3", "MODE_FAST"]);
+ }
+
+ #[test]
+ fn c_integer_literals() {
+ assert_eq!(parse_u64_literal("0"), Some(0));
+ assert_eq!(parse_u64_literal("010"), Some(8));
+ assert_eq!(parse_u64_literal("0755"), Some(0o755));
+ assert_eq!(parse_u64_literal("0x1F"), Some(31));
+ assert_eq!(parse_u64_literal("0b101"), Some(5));
+ assert_eq!(parse_u64_literal("4096UL"), Some(4096));
+ assert_eq!(parse_u64_literal("0xffULL"), Some(255));
+ assert_eq!(parse_u64_literal("08"), None);
+ assert_eq!(parse_u64_literal("0x"), None);
+ assert_eq!(parse_u64_literal("+5"), None);
+ assert_eq!(parse_u64_literal("PAGE_SIZE"), None);
+ assert_eq!(parse_i64_literal("-010"), Some(-8));
+ assert_eq!(parse_i64_literal("-1U"), Some(4294967295));
+ assert_eq!(parse_i64_literal("-0x80000000"), Some(2147483648));
+ assert_eq!(parse_i64_literal("-2147483648"), Some(-2147483648));
+ assert_eq!(parse_i64_literal("-1UL"), Some(-1));
+ assert_eq!(parse_i64_literal("0xFFFFFFFFFFFFFFFF"), Some(-1));
+ assert_eq!(parse_i64_literal("18446744073709551615"), Some(-1));
+ assert_eq!(parse_i64_literal("-0x8000000000000000"), Some(i64::MIN));
+ assert_eq!(parse_u64_literal("-1"), Some(u64::MAX));
+ assert_eq!(parse_u64_literal("1uu"), None);
+ assert_eq!(parse_u64_literal("1lll"), None);
+ }
+
+ #[test]
+ fn parse_constraint_c_literals() {
+ let doc = "\
+sys_c - Constraint test
+param: mode
+ type: int, input
+ constraint-type: enum(010, 0x10, -07, 0b11, 5U)
+param: perms
+ type: uint, input
+ constraint-type: mask(0755)
+param: len
+ type: uint, input
+ constraint-type: range(01, 0x1000UL)
+param: align
+ type: uint, input
+ constraint-type: alignment(0x10)
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_c", "syscall", None)
+ .unwrap();
+
+ let p = &spec.parameters;
+ assert_eq!(p[0].enum_values, ["8", "16", "-7", "3", "5"]);
+ assert_eq!(p[1].valid_mask, Some(0o755));
+ assert_eq!((p[2].min_value, p[2].max_value), (Some(1), Some(4096)));
+ assert_eq!(p[3].alignment, Some(16));
+ }
+
+ #[test]
+ fn zero_user_string_limits_are_unset() {
+ let doc = "\
+sys_s - String test
+param: name
+ type: user_ptr, input
+ range: 0, 255
+ constraint-type: user_string
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_s", "syscall", None)
+ .unwrap();
+
+ let p = &spec.parameters[0];
+ assert_eq!(p.constraint_type, 8);
+ assert_eq!((p.min_value, p.max_value), (None, Some(255)));
+ }
+
+ #[test]
+ fn user_ptr_type_implies_user_flag() {
+ let doc = "\
+sys_u - Implicit user flag test
+param: buf
+ type: user_ptr, output
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_u", "syscall", None)
+ .unwrap();
+
+ let p = &spec.parameters[0];
+ assert_eq!(p.param_type, 10); // KAPI_TYPE_USER_PTR
+ assert_eq!(
+ p.flags,
+ (1 << 1) | (1 << 6), // OUT | USER
+ "user_ptr type must imply KAPI_PARAM_USER"
+ );
+ }
+
+ #[test]
+ fn fd_type_does_not_imply_user_flag() {
+ // Only user_ptr / path imply KAPI_PARAM_USER. fd, int, uint,
+ // and every other non-user-space type must leave flags alone.
+ let doc = "\
+sys_fd - fd has no implicit user flag
+param: fd
+ type: fd, input
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_fd", "syscall", None)
+ .unwrap();
+
+ let p = &spec.parameters[0];
+ assert_eq!(p.param_type, 9);
+ assert_eq!(p.flags, 1, "fd must not auto-set KAPI_PARAM_USER");
+ }
+
+ #[test]
+ fn path_type_implies_user_flag() {
+ let doc = "\
+sys_p - Path implicit user flag
+param: filename
+ type: path, input
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_p", "syscall", None)
+ .unwrap();
+
+ let p = &spec.parameters[0];
+ assert_eq!(p.param_type, 11);
+ assert_eq!(
+ p.flags,
+ 1 | (1 << 6), // IN | USER
+ "path type must imply KAPI_PARAM_USER"
+ );
+ }
+
+ #[test]
+ fn short_form_enum_equivalence() {
+ // Short-form and long-form renderings of the same spec must
+ // produce identical ApiSpec output across every enum family:
+ // context flags, param type+flags, constraint type, lock type,
+ // signal direction/action/timing, capability action, side-effect
+ // bitmask, return check type.
+ let long = "\
+sys_x - Enum short form test
+context-flags: KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE
+
+param: fd
+ type: KAPI_TYPE_FD
+ flags: KAPI_PARAM_IN
+
+lock: files->file_lock
+ type: KAPI_LOCK_SPINLOCK
+ scope: acquires
+ desc: table lock
+
+signal: pending_signals
+ direction: KAPI_SIGNAL_RECEIVE
+ action: KAPI_SIGNAL_ACTION_RETURN
+ timing: KAPI_SIGNAL_TIME_DURING
+ desc: sig
+
+capability: CAP_SYS_ADMIN
+ type: KAPI_CAP_BYPASS_CHECK
+
+return:
+ type: KAPI_TYPE_INT
+ check-type: KAPI_RETURN_FD
+ desc: fd or errno
+
+side-effect: KAPI_EFFECT_RESOURCE_CREATE | KAPI_EFFECT_ALLOC_MEMORY
+ target: t
+ desc: d
+";
+ let short = "\
+sys_x - Enum short form test
+contexts: process, sleepable
+
+param: fd
+ type: fd, input
+
+lock: files->file_lock
+ type: spinlock
+ scope: acquires
+ desc: table lock
+
+signal: pending_signals
+ direction: receive
+ action: return
+ timing: during
+ desc: sig
+
+capability: CAP_SYS_ADMIN
+ type: bypass_check
+
+return:
+ type: int
+ check-type: fd
+ desc: fd or errno
+
+side-effect: resource_create | alloc_memory
+ target: t
+ desc: d
+";
+ let mut sp_l = parser()
+ .parse_kerneldoc(long, "sys_x", "syscall", None)
+ .unwrap();
+ let mut sp_s = parser()
+ .parse_kerneldoc(short, "sys_x", "syscall", None)
+ .unwrap();
+ // The return type name is the human spelling, kept as written.
+ for sp in [&mut sp_l, &mut sp_s] {
+ sp.return_spec.as_mut().unwrap().type_name.clear();
+ }
+ assert_eq!(
+ format!("{:#?}", sp_l),
+ format!("{:#?}", sp_s),
+ "long-form and short-form of every enum family must normalise identically"
+ );
+ }
+
+ #[test]
+ fn parse_buffer_short_captures_size_param_idx() {
+ let doc = "\
+sys_b - Buffer test
+param: buf
+ type: user_ptr, output, user
+ constraint-type: buffer(2)
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_b", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.parameters[0].constraint_type, 11);
+ assert_eq!(spec.parameters[0].size_param_idx, Some(2));
+ }
+
+ #[test]
+ fn buffer_short_and_size_param_long_are_symmetric() {
+ let short = "\
+sys_b - Symmetric buffer test
+param: buf
+ type: user_ptr, output, user
+ constraint-type: buffer(2)
+";
+ let long = "\
+sys_b - Symmetric buffer test
+param: buf
+ type: KAPI_TYPE_USER_PTR
+ flags: KAPI_PARAM_OUT | KAPI_PARAM_USER
+ constraint-type: KAPI_CONSTRAINT_BUFFER
+ size-param: 2
+";
+ let sp_s = parser()
+ .parse_kerneldoc(short, "sys_b", "syscall", None)
+ .unwrap();
+ let sp_l = parser()
+ .parse_kerneldoc(long, "sys_b", "syscall", None)
+ .unwrap();
+ assert_eq!(format!("{:#?}", sp_s), format!("{:#?}", sp_l));
+ }
+
+ #[test]
+ fn parse_constraint_type_bare_user_path() {
+ let doc = "\
+sys_c - Constraint test
+param: filename
+ type: path, input, user
+ constraint-type: user_path
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_c", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.parameters[0].constraint_type, 9); // USER_PATH
+ }
+
+ #[test]
+ fn starts_subfield_requires_known_key() {
+ let keys = block_subfield_keys(&BlockContext::SideEffect);
+ assert!(super::starts_subfield("target: file table", keys));
+ assert!(super::starts_subfield("condition:", keys));
+ assert!(super::starts_subfield("reversible: yes", keys));
+ // A colon inside prose does not open a subfield.
+ assert!(!super::starts_subfield(
+ "this lock mid-operation: the handler",
+ keys
+ ));
+ assert!(!super::starts_subfield("Careful: it is dangerous", keys));
+ // A key that belongs to another block type does not count.
+ assert!(!super::starts_subfield("direction: receive", keys));
+ assert!(!super::starts_subfield("O_RDONLY | O_WRONLY |", keys));
+ assert!(!super::starts_subfield(")", keys));
+ }
+
+ #[test]
+ fn multiline_fold_stops_at_sibling_block_attribute() {
+ // The constraint-type's continuation must not greedily eat the
+ // next subfield of the same block.
+ let doc = "\
+sys_y - Fold stop test
+param: f
+ type: int, input
+ constraint-type: mask(FOO |
+ BAR)
+ cdesc: something about f
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_y", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.parameters.len(), 1);
+ // If the fold over-consumed, `cdesc:` would have been swallowed
+ // into the mask expression and param.constraint_type would be 0.
+ assert_eq!(spec.parameters[0].constraint_type, 2);
+ assert_eq!(
+ spec.parameters[0].constraint.as_deref(),
+ Some("something about f")
+ );
+ }
+
+ #[test]
+ fn parse_constraint_type_mask_expr_multiline() {
+ // Real-world sys_open/flags case: a symbolic mask split across
+ // four continuation lines. The parser must fold the continuation
+ // lines before running the function-call match, otherwise the
+ // constraint type silently decays to 0.
+ let doc = "\
+sys_x - Multi-line mask test
+param: f
+ type: int, input
+ constraint-type: mask(O_RDONLY | O_WRONLY | O_RDWR | O_CREAT | O_EXCL | O_NOCTTY |
+ O_TRUNC | O_APPEND | O_NONBLOCK | O_DSYNC | O_SYNC | FASYNC |
+ O_DIRECT | O_LARGEFILE | O_DIRECTORY | O_NOFOLLOW | O_NOATIME |
+ O_CLOEXEC | O_PATH | O_TMPFILE)
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_x", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.parameters.len(), 1);
+ let p = &spec.parameters[0];
+ assert_eq!(p.constraint_type, 2, "multi-line mask must set MASK type");
+ // Symbolic mask: must stay unresolved rather than becoming Some(0).
+ assert_eq!(
+ p.valid_mask, None,
+ "symbolic mask values must remain None, not Some(0)"
+ );
+ }
+
+ #[test]
+ fn parse_constraint_long_form() {
+ let doc = "\
+sys_c - Constraint test
+param: foo
+ type: uint, input
+ constraint-type: KAPI_CONSTRAINT_MASK
+ valid-mask: 0xff
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_c", "syscall", None)
+ .unwrap();
+
+ let p = &spec.parameters[0];
+ assert_eq!(p.constraint_type, 2); // KAPI_CONSTRAINT_MASK
+ }
+
+ #[test]
+ fn parse_constraint_free_text() {
+ // `constraint:` carries free-text constraint description;
+ // function-call short form lives on `constraint-type:`.
+ let doc = "\
+sys_c - Constraint test
+param: foo
+ type: uint, input
+ constraint: must be a valid page descriptor
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_c", "syscall", None)
+ .unwrap();
+
+ let p = &spec.parameters[0];
+ assert_eq!(p.constraint_type, 0);
+ assert_eq!(
+ p.constraint.as_deref(),
+ Some("must be a valid page descriptor")
+ );
+ }
+
+ #[test]
+ fn parse_description_alias_overrides_kerneldoc() {
+ // `description:` inside a `param:` block is an alias for `desc:`
+ // and overrides the @param description.
+ let doc = "\
+sys_d - Description alias test
+@size: kerneldoc short description
+param: size
+ type: uint, input
+ description: The new long form description.
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_d", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.parameters.len(), 1);
+ assert_eq!(
+ spec.parameters[0].description,
+ "The new long form description."
+ );
+ }
+
+ #[test]
+ fn canonical_equivalence_short_vs_long() {
+ // Two spellings of the same spec must produce identical ApiSpec
+ // JSON.
+ let long = "\
+sys_open - open a file
+context-flags: KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE
+
+param: filename
+ type: KAPI_TYPE_PATH
+ flags: KAPI_PARAM_IN | KAPI_PARAM_USER
+ constraint-type: KAPI_CONSTRAINT_USER_PATH
+ desc: Pathname to open
+
+param: count
+ type: KAPI_TYPE_UINT
+ flags: KAPI_PARAM_IN
+ constraint-type: KAPI_CONSTRAINT_RANGE
+ range: 0, 4096
+ desc: Byte count
+";
+ let short = "\
+sys_open - open a file
+contexts: process, sleepable
+
+param: filename
+ type: path, input, user
+ constraint-type: user_path
+ description: Pathname to open
+
+param: count
+ type: uint, input
+ constraint-type: range(0, 4096)
+ description: Byte count
+";
+ let long_spec = parser()
+ .parse_kerneldoc(long, "sys_open", "syscall", None)
+ .unwrap();
+ let short_spec = parser()
+ .parse_kerneldoc(short, "sys_open", "syscall", None)
+ .unwrap();
+
+ // ApiSpec isn't Serialize as a whole, so compare the Debug
+ // rendering, which still proves every field canonicalises
+ // identically.
+ let d_long = format!("{:#?}", long_spec);
+ let d_short = format!("{:#?}", short_spec);
+ assert_eq!(
+ d_long, d_short,
+ "short-form and long-form specs must normalise identically"
+ );
+ }
+
+ #[test]
+ fn parse_capability_block() {
+ let doc = "\
+sys_cap - Capability test
+capability: CAP_SYS_ADMIN
+ type: required
+ allows: Full system administration
+ without: Operation not permitted
+ condition: always
+ priority: 5
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_cap", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.capabilities.len(), 1);
+ let cap = &spec.capabilities[0];
+ assert_eq!(cap.capability, 21); // CAP_SYS_ADMIN
+ assert_eq!(cap.action, "required");
+ assert_eq!(cap.allows, "Full system administration");
+ assert_eq!(cap.without_cap, "Operation not permitted");
+ assert_eq!(cap.check_condition.as_deref(), Some("always"));
+ assert_eq!(cap.priority, Some(5));
+ }
+
+ #[test]
+ fn parse_lock_block() {
+ let doc = "\
+sys_lock - Lock test
+lock: files_lock, KAPI_LOCK_MUTEX
+ scope: acquires
+ desc: Protects file table
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_lock", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.locks.len(), 1);
+ let lock = &spec.locks[0];
+ assert_eq!(lock.lock_name, "files_lock");
+ assert_eq!(lock.lock_type, 1); // MUTEX
+ assert_eq!(lock.scope, super::super::KAPI_LOCK_ACQUIRES);
+ assert_eq!(lock.description, "Protects file table");
+ }
+
+ #[test]
+ fn parse_lock_acquired_released_flags() {
+ let doc = "\
+sys_lock - Lock test
+lock: a_lock, KAPI_LOCK_MUTEX
+ acquired: true
+ released: true
+lock: b_lock, KAPI_LOCK_MUTEX
+ acquired: true
+lock: c_lock, KAPI_LOCK_MUTEX
+ released: yes
+lock: d_lock, KAPI_LOCK_MUTEX
+ acquired: conditional
+ released: false
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_lock", "syscall", None)
+ .unwrap();
+
+ let scopes: Vec<u32> = spec.locks.iter().map(|l| l.scope).collect();
+ assert_eq!(
+ scopes,
+ vec![
+ super::super::KAPI_LOCK_INTERNAL,
+ super::super::KAPI_LOCK_ACQUIRES,
+ super::super::KAPI_LOCK_RELEASES,
+ super::super::KAPI_LOCK_INTERNAL,
+ ]
+ );
+ }
+
+ #[test]
+ fn parse_signal_block() {
+ let doc = "\
+sys_sig - Signal test
+signal: SIGKILL
+ direction: KAPI_SIGNAL_RECEIVE
+ action: KAPI_SIGNAL_ACTION_TERMINATE
+ timing: KAPI_SIGNAL_TIME_DURING
+ priority: 3
+ restartable: yes
+ interruptible: yes
+ desc: Process termination signal
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_sig", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.signals.len(), 1);
+ let sig = &spec.signals[0];
+ assert_eq!(sig.signal_name, "SIGKILL");
+ assert_eq!(sig.direction, 1); // RECEIVE
+ assert_eq!(sig.action, 1); // TERMINATE
+ assert_eq!(sig.timing, 1); // DURING
+ assert_eq!(sig.priority, 3);
+ assert!(sig.restartable);
+ assert!(sig.interruptible);
+ assert_eq!(
+ sig.description.as_deref(),
+ Some("Process termination signal")
+ );
+ }
+
+ #[test]
+ fn parse_signal_errno_shapes() {
+ // All three accepted spellings of the signal errno field must
+ // produce the same negative kernel return code.
+ for (form, label) in [
+ ("errno: -EINTR", "-EINTR symbolic"),
+ ("errno: EINTR", "bare symbolic"),
+ ("errno: -4", "numeric literal"),
+ ] {
+ let doc = format!(
+ "sys_s - Signal errno test\n\
+ signal: SIGINT\n\
+ \x20 direction: receive\n\
+ \x20 action: return\n\
+ \x20 {}\n",
+ form,
+ );
+ let spec = parser()
+ .parse_kerneldoc(&doc, "sys_s", "syscall", None)
+ .unwrap();
+ assert_eq!(spec.signals.len(), 1, "{label}");
+ assert_eq!(
+ spec.signals[0].error_on_signal,
+ Some(-4),
+ "errno form {label:?} must resolve to -EINTR (-4)",
+ );
+ }
+ }
+
+ #[test]
+ fn parse_side_effect_flat() {
+ let doc = "\
+sys_se - Side effect test
+side-effect: KAPI_EFFECT_MODIFY_STATE, file_table, Allocates a new file descriptor
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_se", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.side_effects.len(), 1);
+ let se = &spec.side_effects[0];
+ assert_eq!(se.effect_type, 1 << 2); // KAPI_EFFECT_MODIFY_STATE
+ assert_eq!(se.target, "file_table");
+ assert_eq!(se.description, "Allocates a new file descriptor");
+ }
+
+ #[test]
+ fn parse_side_effect_block() {
+ let doc = "\
+sys_se2 - Side effect block test
+side-effect: KAPI_EFFECT_ALLOC_MEMORY
+ target: kernel_heap
+ desc: Allocates kernel memory
+ reversible: yes
+ condition: size > 0
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_se2", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.side_effects.len(), 1);
+ let se = &spec.side_effects[0];
+ assert_eq!(se.effect_type, 1 << 0); // KAPI_EFFECT_ALLOC_MEMORY
+ assert_eq!(se.target, "kernel_heap");
+ assert_eq!(se.description, "Allocates kernel memory");
+ assert!(se.reversible);
+ assert_eq!(se.condition.as_deref(), Some("size > 0"));
+ }
+
+ #[test]
+ fn parse_empty_doc_no_error() {
+ let doc = "";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_empty", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.name, "sys_empty");
+ assert!(spec.description.is_none());
+ assert!(spec.parameters.is_empty());
+ assert!(spec.errors.is_empty());
+ assert!(spec.signals.is_empty());
+ assert!(spec.capabilities.is_empty());
+ assert!(spec.locks.is_empty());
+ assert!(spec.side_effects.is_empty());
+ assert!(spec.context_flags.is_empty());
+ }
+
+ #[test]
+ fn parse_missing_sections_no_error() {
+ // Only has a description, no KAPI annotations
+ let doc = "\
+sys_simple - Just a simple syscall
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_simple", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.description.as_deref(), Some("Just a simple syscall"));
+ assert!(spec.parameters.is_empty());
+ assert!(spec.errors.is_empty());
+ assert!(spec.context_flags.is_empty());
+ }
+
+ #[test]
+ fn parse_constraint_block() {
+ let doc = "\
+sys_cst - Constraint test
+constraint: valid_fd
+ desc: File descriptor must be valid and open
+ expr: fd >= 0 && fd < NR_OPEN
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_cst", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.constraints.len(), 1);
+ let cst = &spec.constraints[0];
+ assert_eq!(cst.name, "valid_fd");
+ assert_eq!(cst.description, "File descriptor must be valid and open");
+ assert_eq!(cst.expression.as_deref(), Some("fd >= 0 && fd < NR_OPEN"));
+ }
+
+ #[test]
+ fn parse_state_transition_flat() {
+ let doc = "\
+sys_st - State transition test
+state-trans: fd, open, closed, File descriptor is closed
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_st", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.state_transitions.len(), 1);
+ let st = &spec.state_transitions[0];
+ assert_eq!(st.object, "fd");
+ assert_eq!(st.from_state, "open");
+ assert_eq!(st.to_state, "closed");
+ assert_eq!(st.description, "File descriptor is closed");
+ }
+
+ #[test]
+ fn parse_param_block_with_range() {
+ let doc = "\
+sys_rng - Range test
+@count: byte count
+param: count
+ type: KAPI_TYPE_UINT
+ flags: IN
+ range: 0, 4096
+ constraint-type: KAPI_CONSTRAINT_RANGE
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_rng", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.parameters.len(), 1);
+ let p = &spec.parameters[0];
+ assert_eq!(p.name, "count");
+ assert_eq!(p.param_type, 2); // UINT
+ assert_eq!(p.flags, 1); // IN
+ assert_eq!(p.min_value, Some(0));
+ assert_eq!(p.max_value, Some(4096));
+ assert_eq!(p.constraint_type, 1); // RANGE
+ }
+
+ #[test]
+ fn parse_return_block() {
+ let doc = "\
+sys_ret - Return test
+return:
+ type: KAPI_TYPE_INT
+ check-type: KAPI_RETURN_FD
+ success: 0
+ desc: Returns file descriptor on success
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_ret", "syscall", None)
+ .unwrap();
+
+ let ret = spec.return_spec.as_ref().unwrap();
+ assert_eq!(ret.type_name, "KAPI_TYPE_INT");
+ assert_eq!(ret.return_type, 1); // INT
+ assert_eq!(ret.check_type, 3); // FD
+ assert_eq!(ret.success_value, None); // FD checks carry no success value
+ assert_eq!(ret.description, "Returns file descriptor on success");
+ }
+
+ #[test]
+ fn colon_in_continuation_line_does_not_start_subfield() {
+ let doc = "\
+sys_col - Colon continuation test
+param: x
+ type: int
+ cdesc: Must be sane. Note: this is a continuation
+ with a colon: in the middle.
+
+lock: mylock
+ type: mutex
+ desc: Taken at entry; if the caller drops
+ this lock mid-operation: the handler waits
+ until released.
+
+side-effect: modify_state
+ target: stuff
+ condition: only when a
+ special case applies: for example
+ on Tuesdays
+ desc: Does things.
+ Careful: it is dangerous.
+ reversible: no
+
+signal: SIGINT
+ direction: receive
+ condition: while blocked, unless
+ flagged: see below
+ desc: Interrupts the wait.
+
+capability: CAP_SYS_ADMIN
+ type: bypass_check
+ allows: Things
+ that need: privilege
+ condition: Always
+
+constraint: limit
+ desc: A limit
+ of note: nothing.
+ expr: a &&
+ b
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_col", "syscall", None)
+ .unwrap();
+
+ assert_eq!(
+ spec.parameters[0].constraint.as_deref(),
+ Some("Must be sane. Note: this is a continuation with a colon: in the middle.")
+ );
+ assert_eq!(
+ spec.locks[0].description,
+ "Taken at entry; if the caller drops this lock mid-operation: the handler waits until released."
+ );
+ let se = &spec.side_effects[0];
+ assert_eq!(
+ se.condition.as_deref(),
+ Some("only when a special case applies: for example on Tuesdays")
+ );
+ assert_eq!(se.description, "Does things. Careful: it is dangerous.");
+ assert!(!se.reversible);
+ let sig = &spec.signals[0];
+ assert_eq!(
+ sig.condition.as_deref(),
+ Some("while blocked, unless flagged: see below")
+ );
+ assert_eq!(sig.description.as_deref(), Some("Interrupts the wait."));
+ let cap = &spec.capabilities[0];
+ assert_eq!(cap.allows, "Things that need: privilege");
+ assert_eq!(cap.check_condition.as_deref(), Some("Always"));
+ let cst = &spec.constraints[0];
+ assert_eq!(cst.description, "A limit of note: nothing.");
+ assert_eq!(cst.expression.as_deref(), Some("a && b"));
+ }
+
+ #[test]
+ fn multiline_side_effect_condition_is_kept_whole() {
+ let doc = "\
+sys_mc - Multi-line condition test
+side-effect: modify_state
+ target: userfaultfd event queue
+ condition: MADV_DONTNEED, MADV_FREE
+ on a VMA whose userfaultfd context negotiated
+ UFFD_FEATURE_EVENT_REMOVE
+ desc: Generates a notification.
+ The monitor cannot veto it.
+ reversible: no
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_mc", "syscall", None)
+ .unwrap();
+
+ let se = &spec.side_effects[0];
+ assert_eq!(
+ se.condition.as_deref(),
+ Some(
+ "MADV_DONTNEED, MADV_FREE on a VMA whose userfaultfd context \
+ negotiated UFFD_FEATURE_EVENT_REMOVE"
+ )
+ );
+ assert_eq!(
+ se.description,
+ "Generates a notification. The monitor cannot veto it."
+ );
+ }
+
+ #[test]
+ fn blank_line_inside_block_continues_subfield() {
+ let doc = "\
+sys_bl - Blank line test
+lock: l
+ type: mutex
+ desc: First half
+
+ second half.
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_bl", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.locks[0].description, "First half second half.");
+ }
+
+ #[test]
+ fn param_cdesc_is_the_constraint_text() {
+ let doc = "\
+sys_cd - cdesc test
+param: fd
+ type: int, input
+ cdesc: Must be open.
+ Zero is allowed.
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_cd", "syscall", None)
+ .unwrap();
+
+ assert_eq!(
+ spec.parameters[0].constraint.as_deref(),
+ Some("Must be open. Zero is allowed.")
+ );
+ }
+
+ #[test]
+ fn state_transition_block_keeps_condition_separate() {
+ let doc = "\
+sys_stb - State transition block test
+state-trans: file_descriptor
+ from: open
+ to: closed/free
+ condition: Valid fd passed to close
+ desc: The fd becomes unusable.
+ It may be reused.
+
+state-trans: refcount
+ from: n
+ to: n-1
+ desc: Decremented.
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_stb", "syscall", None)
+ .unwrap();
+
+ assert_eq!(spec.state_transitions.len(), 2);
+ let st = &spec.state_transitions[0];
+ assert_eq!(st.object, "file_descriptor");
+ assert_eq!(st.from_state, "open");
+ assert_eq!(st.to_state, "closed/free");
+ assert_eq!(st.condition.as_deref(), Some("Valid fd passed to close"));
+ assert_eq!(st.description, "The fd becomes unusable. It may be reused.");
+ let st = &spec.state_transitions[1];
+ assert_eq!(st.object, "refcount");
+ assert_eq!(st.condition, None);
+ assert_eq!(st.description, "Decremented.");
+ }
+
+ #[test]
+ fn state_transition_flat_description_keeps_commas() {
+ let doc = "\
+sys_stc - Flat state transition test
+state-trans: fd, open, closed, File is closed, and the number is free
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_stc", "syscall", None)
+ .unwrap();
+
+ let st = &spec.state_transitions[0];
+ assert_eq!(st.description, "File is closed, and the number is free");
+ assert_eq!(st.condition, None);
+ }
+
+ #[test]
+ fn return_type_name_is_kept_as_written() {
+ for (written, ty) in [("int", 1), ("long", 0), ("KAPI_TYPE_UINT", 2)] {
+ let doc = format!("sys_rt - Return type test\nreturn:\n type: {written}\n");
+ let spec = parser()
+ .parse_kerneldoc(&doc, "sys_rt", "syscall", None)
+ .unwrap();
+ let ret = spec.return_spec.as_ref().unwrap();
+ assert_eq!(ret.type_name, written);
+ assert_eq!(ret.return_type, ty);
+ }
+ }
+
+ #[test]
+ fn return_success_follows_check_type() {
+ let cases = [
+ // (check-type, success, value, min, max)
+ ("exact", "0", Some(0), None, None),
+ ("exact", "= 0", Some(0), None, None),
+ ("exact", "== -1", Some(-1), None, None),
+ ("exact", "0x10", Some(16), None, None),
+ ("exact", ">= 0", None, None, None),
+ ("range", ">= 0", None, Some(0), Some(i64::MAX)),
+ ("range", ">= 1", None, Some(1), Some(i64::MAX)),
+ ("range", "0", None, Some(0), Some(i64::MAX)),
+ ("fd", ">= 0", None, None, None),
+ ("error_check", "0", None, None, None),
+ ];
+ for (check, success, value, min, max) in cases {
+ let doc = format!(
+ "sys_rs - Return success test\nreturn:\n type: int\n \
+ success: {success}\n check-type: {check}\n desc: ok\n"
+ );
+ let spec = parser()
+ .parse_kerneldoc(&doc, "sys_rs", "syscall", None)
+ .unwrap();
+ let ret = spec.return_spec.as_ref().unwrap();
+ assert_eq!(ret.success_value, value, "{check} {success}");
+ assert_eq!(ret.success_min, min, "{check} {success}");
+ assert_eq!(ret.success_max, max, "{check} {success}");
+ }
+ }
+
+ #[test]
+ fn return_description_continuation_with_colon() {
+ let doc = "\
+sys_rd - Return description test
+return:
+ type: int
+ check-type: exact
+ success: 0
+ desc: Returns zero on success. Note: this is
+ a continuation line with a colon.
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_rd", "syscall", None)
+ .unwrap();
+
+ let ret = spec.return_spec.as_ref().unwrap();
+ assert_eq!(
+ ret.description,
+ "Returns zero on success. Note: this is a continuation line with a colon."
+ );
+ assert_eq!(ret.success_value, Some(0));
+ }
+
+ #[test]
+ fn examples_keep_one_example_per_line() {
+ let doc = "\
+sys_ex - Examples test
+examples: fd = open(\"/etc/passwd\", O_RDONLY); // Read existing file
+ fd = open(\"/tmp/new\", O_WRONLY | O_CREAT, 0644); // Create
+ // Handle short writes:
+ while (total < len) {
+ n = write(fd, buf + total, len - total);
+ if (n < 0) break;
+ }
+
+ close(fd);
+
+notes: After the examples.
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_ex", "syscall", None)
+ .unwrap();
+
+ assert_eq!(
+ spec.examples.as_deref(),
+ Some(
+ "fd = open(\"/etc/passwd\", O_RDONLY); // Read existing file\n\
+ fd = open(\"/tmp/new\", O_WRONLY | O_CREAT, 0644); // Create\n\
+ // Handle short writes:\n\
+ while (total < len) {\n \
+ n = write(fd, buf + total, len - total);\n \
+ if (n < 0) break;\n\
+ }\n\
+ \n\
+ close(fd);"
+ )
+ );
+ assert_eq!(spec.notes.as_deref(), Some("After the examples."));
+ }
+
+ #[test]
+ fn notes_and_long_desc_keep_paragraphs_and_bullets() {
+ let doc = "\
+sys_nt - Notes test
+long-desc: First paragraph wraps
+ over two lines.
+
+ Second paragraph introduces a list:
+ - item one wraps
+ onto a second line
+ - item two
+
+ Last paragraph.
+notes: The behavior varies:
+
+ - Regular files: reads
+ from the current position.
+
+ - Pipes: block.
+
+ Trailing: text.
+";
+ let spec = parser()
+ .parse_kerneldoc(doc, "sys_nt", "syscall", None)
+ .unwrap();
+
+ assert_eq!(
+ spec.long_description.as_deref(),
+ Some(
+ "First paragraph wraps over two lines.\n\n\
+ Second paragraph introduces a list:\n\
+ - item one wraps onto a second line\n\
+ - item two\n\n\
+ Last paragraph."
+ )
+ );
+ assert_eq!(
+ spec.notes.as_deref(),
+ Some(
+ "The behavior varies:\n\n\
+ - Regular files: reads from the current position.\n\n\
+ - Pipes: block.\n\n\
+ Trailing: text."
+ )
+ );
+ }
+
+ #[test]
+ fn fold_lines_handles_leading_blank_and_tabs() {
+ assert_eq!(
+ super::fold_lines(&["", " a();", " b();", " c();", ""]),
+ "a();\nb();\n c();"
+ );
+ assert_eq!(super::fold_lines(&["x();", "\ty();"]), "x();\ny();");
+ assert_eq!(super::fold_lines(&[""]), "");
+ assert_eq!(super::fold_lines(&["a", " b", "", "", " c"]), "a\nb\n\nc");
+ }
+
+ #[test]
+ fn fold_paragraphs_joins_wrapped_lines_only() {
+ assert_eq!(
+ super::fold_paragraphs(&["one", " two", "", "", " three", "- four", "- five"]),
+ "one two\n\nthree\n- four\n- five"
+ );
+ assert_eq!(super::fold_paragraphs(&["", " "]), "");
+ }
+}
--git a/tools/kapi/src/extractor/mod.rs b/tools/kapi/src/extractor/mod.rs
new file mode 100644
index 0000000000000..d7ada57924d7a
--- /dev/null
+++ b/tools/kapi/src/extractor/mod.rs
@@ -0,0 +1,442 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+use crate::formatter::OutputFormatter;
+use anyhow::Result;
+use std::io::Write;
+
+pub mod debugfs;
+pub mod kerneldoc_parser;
+pub mod source_parser;
+pub mod vmlinux;
+
+pub use debugfs::DebugfsExtractor;
+pub use source_parser::SourceExtractor;
+pub use vmlinux::VmlinuxExtractor;
+
+/// Capability specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct CapabilitySpec {
+ pub capability: i32,
+ pub name: String,
+ pub action: String,
+ pub allows: String,
+ pub without_cap: String,
+ pub check_condition: Option<String>,
+ pub priority: Option<u8>,
+ pub alternatives: Vec<i32>,
+}
+
+/// Parameter specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct ParamSpec {
+ pub index: u32,
+ pub name: String,
+ pub type_name: String,
+ pub description: String,
+ pub flags: u32,
+ pub param_type: u32,
+ pub constraint_type: u32,
+ pub constraint: Option<String>,
+ pub min_value: Option<i64>,
+ pub max_value: Option<i64>,
+ pub valid_mask: Option<u64>,
+ pub enum_values: Vec<String>,
+ pub size: Option<u32>,
+ pub alignment: Option<u32>,
+ /// Index of the parameter that carries this parameter's byte count
+ /// (for KAPI_CONSTRAINT_BUFFER). Populated by either
+ /// `size-param: N` (long form) or `constraint-type: buffer(N)`
+ /// (short form).
+ pub size_param_idx: Option<u32>,
+}
+
+/// Constraint type enum values matching kernel enum kapi_constraint_type
+pub const KAPI_CONSTRAINT_RANGE: u32 = 1;
+pub const KAPI_CONSTRAINT_MASK: u32 = 2;
+pub const KAPI_CONSTRAINT_USER_STRING: u32 = 8;
+
+impl ParamSpec {
+ /// Clear the numeric fields the constraint type does not use. The
+ /// compiled struct always carries them, so an unset value reads as 0.
+ pub fn keep_used_numbers(&mut self) {
+ match self.constraint_type {
+ KAPI_CONSTRAINT_RANGE => {}
+ KAPI_CONSTRAINT_USER_STRING => self.drop_unset_string_limits(),
+ _ => {
+ self.min_value = None;
+ self.max_value = None;
+ }
+ }
+ if self.constraint_type != KAPI_CONSTRAINT_MASK {
+ self.valid_mask = None;
+ }
+ self.size = self.size.filter(|&n| n != 0);
+ self.alignment = self.alignment.filter(|&n| n != 0);
+ }
+
+ /// The kernel treats a user_string length limit of 0 as no limit.
+ pub fn drop_unset_string_limits(&mut self) {
+ if self.constraint_type == KAPI_CONSTRAINT_USER_STRING {
+ self.min_value = self.min_value.filter(|&n| n > 0);
+ self.max_value = self.max_value.filter(|&n| n > 0);
+ }
+ }
+}
+
+/// Return value specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct ReturnSpec {
+ pub type_name: String,
+ pub description: String,
+ pub return_type: u32,
+ pub check_type: u32,
+ pub success_value: Option<i64>,
+ pub success_min: Option<i64>,
+ pub success_max: Option<i64>,
+ pub error_values: Vec<i32>,
+}
+
+impl ReturnSpec {
+ /// Drop the success fields the check type does not use, the way the
+ /// generated KAPI_RETURN_SUCCESS()/KAPI_RETURN_SUCCESS_RANGE() macros
+ /// only set the one that applies.
+ pub fn keep_used_success_fields(&mut self) {
+ match self.check_type {
+ 0 => {
+ self.success_min = None;
+ self.success_max = None;
+ }
+ 1 => self.success_value = None,
+ _ => {
+ self.success_value = None;
+ self.success_min = None;
+ self.success_max = None;
+ }
+ }
+ }
+}
+
+/// Error specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct ErrorSpec {
+ pub error_code: i32,
+ pub name: String,
+ pub condition: String,
+ pub description: String,
+}
+
+/// Signal specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct SignalSpec {
+ pub signal_num: i32,
+ pub signal_name: String,
+ pub direction: u32,
+ pub action: u32,
+ pub target: Option<String>,
+ pub condition: Option<String>,
+ pub description: Option<String>,
+ pub timing: u32,
+ pub priority: u32,
+ pub restartable: bool,
+ pub interruptible: bool,
+ pub queue: Option<String>,
+ pub sa_flags: u32,
+ pub sa_flags_required: u32,
+ pub sa_flags_forbidden: u32,
+ pub state_required: u32,
+ pub state_forbidden: u32,
+ pub error_on_signal: Option<i32>,
+ /// Signal number to transform to (e.g. `SIGKILL` -> 9 on x86).
+ /// Always an integer or null in JSON -- the schema never widens to
+ /// a string. Extractors reading the compiled struct (`--vmlinux`,
+ /// `--debugfs`) populate this directly. The source-kerneldoc parser
+ /// populates it only when the `transform-to:` subfield is a numeric
+ /// literal; symbolic signal names are arch-dependent and cannot be
+ /// resolved portably in userspace, so they are reported via an
+ /// stderr warning and leave this field `None`. Consumers that need
+ /// the resolved number for a symbolic spec should use `--vmlinux`
+ /// or `--debugfs` against a kernel built for the target arch.
+ pub transform_to: Option<i32>,
+}
+
+/// Signal mask specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct SignalMaskSpec {
+ pub name: String,
+ pub description: String,
+ pub signals: Vec<i32>,
+}
+
+/// Side effect specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct SideEffectSpec {
+ pub effect_type: u32,
+ pub target: String,
+ pub condition: Option<String>,
+ pub description: String,
+ pub reversible: bool,
+}
+
+/// State transition specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct StateTransitionSpec {
+ pub object: String,
+ pub from_state: String,
+ pub to_state: String,
+ pub condition: Option<String>,
+ pub description: String,
+}
+
+/// Constraint specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct ConstraintSpec {
+ pub name: String,
+ pub description: String,
+ pub expression: Option<String>,
+}
+
+/// Lock scope enum values matching kernel enum kapi_lock_scope
+pub const KAPI_LOCK_INTERNAL: u32 = 0;
+pub const KAPI_LOCK_ACQUIRES: u32 = 1;
+pub const KAPI_LOCK_RELEASES: u32 = 2;
+pub const KAPI_LOCK_CALLER_HELD: u32 = 3;
+
+/// Lock specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct LockSpec {
+ pub lock_name: String,
+ pub lock_type: u32,
+ pub scope: u32,
+ pub description: String,
+}
+
+/// Struct field specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct StructFieldSpec {
+ pub name: String,
+ pub field_type: u32,
+ pub type_name: String,
+ pub offset: usize,
+ pub size: usize,
+ pub flags: u32,
+ pub constraint_type: u32,
+ pub min_value: i64,
+ pub max_value: i64,
+ pub valid_mask: u64,
+ pub description: String,
+}
+
+/// Struct specification
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct StructSpec {
+ pub name: String,
+ pub size: usize,
+ pub alignment: usize,
+ pub field_count: u32,
+ pub fields: Vec<StructFieldSpec>,
+ pub description: String,
+}
+
+/// Common API specification information that all extractors should provide
+#[derive(Debug, Clone, Default)]
+pub struct ApiSpec {
+ pub name: String,
+ pub api_type: String,
+ pub description: Option<String>,
+ pub long_description: Option<String>,
+ pub version: Option<String>,
+ pub context_flags: Vec<String>,
+ pub param_count: Option<u32>,
+ pub error_count: Option<u32>,
+ pub examples: Option<String>,
+ pub notes: Option<String>,
+ // Sysfs-specific fields
+ pub subsystem: Option<String>,
+ pub sysfs_path: Option<String>,
+ pub permissions: Option<String>,
+ pub capabilities: Vec<CapabilitySpec>,
+ pub parameters: Vec<ParamSpec>,
+ pub return_spec: Option<ReturnSpec>,
+ pub errors: Vec<ErrorSpec>,
+ pub signals: Vec<SignalSpec>,
+ pub signal_masks: Vec<SignalMaskSpec>,
+ pub side_effects: Vec<SideEffectSpec>,
+ pub state_transitions: Vec<StateTransitionSpec>,
+ pub constraints: Vec<ConstraintSpec>,
+ pub locks: Vec<LockSpec>,
+ pub struct_specs: Vec<StructSpec>,
+}
+
+/// Trait for extracting API specifications from different sources
+pub trait ApiExtractor {
+ /// Extract all API specifications from the source
+ fn extract_all(&self) -> Result<Vec<ApiSpec>>;
+
+ /// Extract a specific API specification by name
+ fn extract_by_name(&self, name: &str) -> Result<Option<ApiSpec>>;
+
+ /// Display detailed information about a specific API
+ fn display_api_details(
+ &self,
+ api_name: &str,
+ formatter: &mut dyn OutputFormatter,
+ writer: &mut dyn Write,
+ ) -> Result<()>;
+}
+
+/// Helper function to display an ApiSpec using a formatter
+pub fn display_api_spec(
+ spec: &ApiSpec,
+ formatter: &mut dyn OutputFormatter,
+ writer: &mut dyn Write,
+) -> Result<()> {
+ formatter.begin_api_details(writer, &spec.name)?;
+
+ if let Some(desc) = &spec.description {
+ formatter.description(writer, desc)?;
+ }
+
+ if let Some(long_desc) = &spec.long_description {
+ formatter.long_description(writer, long_desc)?;
+ }
+
+ if !spec.context_flags.is_empty() {
+ formatter.begin_context_flags(writer)?;
+ for flag in &spec.context_flags {
+ formatter.context_flag(writer, flag)?;
+ }
+ formatter.end_context_flags(writer)?;
+ }
+
+ if !spec.parameters.is_empty() {
+ formatter.begin_parameters(writer, spec.parameters.len().try_into().unwrap_or(u32::MAX))?;
+ for param in &spec.parameters {
+ formatter.parameter(writer, param)?;
+ }
+ formatter.end_parameters(writer)?;
+ }
+
+ if let Some(ret) = &spec.return_spec {
+ formatter.return_spec(writer, ret)?;
+ }
+
+ if !spec.errors.is_empty() {
+ formatter.begin_errors(writer, spec.errors.len().try_into().unwrap_or(u32::MAX))?;
+ for error in &spec.errors {
+ formatter.error(writer, error)?;
+ }
+ formatter.end_errors(writer)?;
+ }
+
+ if let Some(notes) = &spec.notes {
+ formatter.notes(writer, notes)?;
+ }
+
+ if let Some(examples) = &spec.examples {
+ formatter.examples(writer, examples)?;
+ }
+
+ // Display sysfs-specific fields
+ if spec.api_type == "sysfs" {
+ if let Some(subsystem) = &spec.subsystem {
+ formatter.sysfs_subsystem(writer, subsystem)?;
+ }
+ if let Some(path) = &spec.sysfs_path {
+ formatter.sysfs_path(writer, path)?;
+ }
+ if let Some(perms) = &spec.permissions {
+ formatter.sysfs_permissions(writer, perms)?;
+ }
+ }
+
+ if !spec.capabilities.is_empty() {
+ formatter.begin_capabilities(writer)?;
+ for cap in &spec.capabilities {
+ formatter.capability(writer, cap)?;
+ }
+ formatter.end_capabilities(writer)?;
+ }
+
+ // Display signals
+ if !spec.signals.is_empty() {
+ formatter.begin_signals(writer, spec.signals.len().try_into().unwrap_or(u32::MAX))?;
+ for signal in &spec.signals {
+ formatter.signal(writer, signal)?;
+ }
+ formatter.end_signals(writer)?;
+ }
+
+ // Display signal masks
+ if !spec.signal_masks.is_empty() {
+ formatter.begin_signal_masks(
+ writer,
+ spec.signal_masks.len().try_into().unwrap_or(u32::MAX),
+ )?;
+ for mask in &spec.signal_masks {
+ formatter.signal_mask(writer, mask)?;
+ }
+ formatter.end_signal_masks(writer)?;
+ }
+
+ // Display side effects
+ if !spec.side_effects.is_empty() {
+ formatter.begin_side_effects(
+ writer,
+ spec.side_effects.len().try_into().unwrap_or(u32::MAX),
+ )?;
+ for effect in &spec.side_effects {
+ formatter.side_effect(writer, effect)?;
+ }
+ formatter.end_side_effects(writer)?;
+ }
+
+ // Display state transitions
+ if !spec.state_transitions.is_empty() {
+ formatter.begin_state_transitions(
+ writer,
+ spec.state_transitions.len().try_into().unwrap_or(u32::MAX),
+ )?;
+ for trans in &spec.state_transitions {
+ formatter.state_transition(writer, trans)?;
+ }
+ formatter.end_state_transitions(writer)?;
+ }
+
+ // Display constraints
+ if !spec.constraints.is_empty() {
+ formatter.begin_constraints(
+ writer,
+ spec.constraints.len().try_into().unwrap_or(u32::MAX),
+ )?;
+ for constraint in &spec.constraints {
+ formatter.constraint(writer, constraint)?;
+ }
+ formatter.end_constraints(writer)?;
+ }
+
+ // Display locks
+ if !spec.locks.is_empty() {
+ formatter.begin_locks(writer, spec.locks.len().try_into().unwrap_or(u32::MAX))?;
+ for lock in &spec.locks {
+ formatter.lock(writer, lock)?;
+ }
+ formatter.end_locks(writer)?;
+ }
+
+ // Display struct specs
+ if !spec.struct_specs.is_empty() {
+ formatter.begin_struct_specs(
+ writer,
+ spec.struct_specs.len().try_into().unwrap_or(u32::MAX),
+ )?;
+ for struct_spec in &spec.struct_specs {
+ formatter.struct_spec(writer, struct_spec)?;
+ }
+ formatter.end_struct_specs(writer)?;
+ }
+
+ formatter.end_api_details(writer)?;
+
+ Ok(())
+}
--git a/tools/kapi/src/extractor/source_parser.rs b/tools/kapi/src/extractor/source_parser.rs
new file mode 100644
index 0000000000000..cc50e15f16c83
--- /dev/null
+++ b/tools/kapi/src/extractor/source_parser.rs
@@ -0,0 +1,531 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+use super::kerneldoc_parser::KerneldocParser;
+use super::{display_api_spec, ApiExtractor, ApiSpec};
+use crate::formatter::OutputFormatter;
+use anyhow::{bail, Context, Result};
+use regex::Regex;
+use std::fs;
+use std::io::Write;
+use std::path::Path;
+use walkdir::WalkDir;
+
+/// Extractor for kernel source files with KAPI-annotated kerneldoc
+pub struct SourceExtractor {
+ path: String,
+ parser: KerneldocParser,
+ syscall_regex: Regex,
+ ioctl_regex: Regex,
+ function_regex: Regex,
+}
+
+impl SourceExtractor {
+ pub fn new(path: &str) -> Result<Self> {
+ if !Path::new(path).exists() {
+ bail!("Source path does not exist: {path}");
+ }
+
+ Ok(SourceExtractor {
+ path: path.to_string(),
+ parser: KerneldocParser::new(),
+ syscall_regex: Regex::new(r"SYSCALL_DEFINE\d+\((\w+)")?,
+ ioctl_regex: Regex::new(r"(?:static\s+)?long\s+(\w+_ioctl)\s*\(")?,
+ function_regex: Regex::new(concat!(
+ r"(?m)^(?:static\s+)?(?:inline\s+)?",
+ r"(?:(?:unsigned\s+)?",
+ r"(?:long|int|void|char|short",
+ r"|struct\s+\w+\s*\*?",
+ r"|[\w_]+_t)",
+ r"\s*\*?\s+)?",
+ r"(\w+)\s*\([^)]*\)",
+ ))?,
+ })
+ }
+
+ fn extract_from_file(&self, path: &Path) -> Result<Vec<ApiSpec>> {
+ let content = fs::read_to_string(path)
+ .with_context(|| format!("Failed to read file: {}", path.display()))?;
+
+ self.extract_from_content(&content)
+ }
+
+ /// Same rule as has-apispec in scripts/Makefile.build: a contexts: (or
+ /// context-flags:) line plus one more KAPI section.
+ fn has_context_line(doc: &str) -> bool {
+ const SECTIONS: &[&str] = &[
+ "api-type:",
+ "param:",
+ "error:",
+ "capability:",
+ "signal:",
+ "lock:",
+ "state-trans:",
+ "constraint:",
+ "side-effect:",
+ "long-desc:",
+ ];
+ let has_line = |keys: &[&str]| {
+ doc.lines()
+ .map(str::trim_start)
+ .any(|l| keys.iter().any(|k| l.starts_with(k)))
+ };
+
+ has_line(&["contexts:", "context-flags:"]) && has_line(SECTIONS)
+ }
+
+ fn extract_from_content(&self, content: &str) -> Result<Vec<ApiSpec>> {
+ let mut specs = Vec::new();
+ let mut in_kerneldoc = false;
+ let mut current_doc = String::new();
+ let lines: Vec<&str> = content.lines().collect();
+ let mut i = 0;
+
+ while i < lines.len() {
+ let line = lines[i];
+
+ // Start of kerneldoc comment
+ if line.trim_start().starts_with("/**") {
+ in_kerneldoc = true;
+ current_doc.clear();
+ i += 1;
+ continue;
+ }
+
+ // Inside kerneldoc comment
+ if in_kerneldoc {
+ if line.contains("*/") {
+ in_kerneldoc = false;
+
+ // Check if this kerneldoc has KAPI annotations
+ if Self::has_context_line(¤t_doc) {
+ // Look ahead for the function declaration
+ if let Some((name, api_type, signature)) =
+ self.find_function_after(&lines, i + 1)
+ {
+ if let Ok(spec) = self.parser.parse_kerneldoc(
+ ¤t_doc,
+ &name,
+ &api_type,
+ Some(&signature),
+ ) {
+ specs.push(spec);
+ }
+ }
+ }
+ } else {
+ // Remove leading asterisk and preserve content
+ let cleaned = if let Some(stripped) = line.trim_start().strip_prefix("*") {
+ if let Some(no_space) = stripped.strip_prefix(' ') {
+ no_space
+ } else {
+ stripped
+ }
+ } else {
+ line.trim_start()
+ };
+ current_doc.push_str(cleaned);
+ current_doc.push('\n');
+ }
+ }
+
+ i += 1;
+ }
+
+ Ok(specs)
+ }
+
+ fn find_function_after(
+ &self,
+ lines: &[&str],
+ start: usize,
+ ) -> Option<(String, String, String)> {
+ for i in start..lines.len().min(start + 10) {
+ let line = lines[i];
+
+ // Skip blank lines and a plain comment before the function
+ let trimmed = line.trim_start();
+ if trimmed.is_empty() || trimmed.starts_with("/*") || trimmed.starts_with('*') {
+ continue;
+ }
+
+ // Check for SYSCALL_DEFINE
+ if let Some(caps) = self.syscall_regex.captures(line) {
+ let name = format!("sys_{}", caps.get(1).unwrap().as_str());
+ let signature = self.extract_syscall_signature(lines, i);
+ return Some((name, "syscall".to_string(), signature));
+ }
+
+ // Check for ioctl function
+ if let Some(caps) = self.ioctl_regex.captures(line) {
+ let name = caps.get(1).unwrap().as_str().to_string();
+ return Some((name, "ioctl".to_string(), line.to_string()));
+ }
+
+ // Check for regular function
+ if let Some(caps) = self.function_regex.captures(line) {
+ let name = caps.get(1).unwrap().as_str().to_string();
+ return Some((name, "function".to_string(), line.to_string()));
+ }
+
+ // Stop if we hit something that's clearly not part of the function declaration
+ if !line.starts_with(' ') && !line.starts_with('\t') && !line.trim().is_empty() {
+ break;
+ }
+ }
+
+ None
+ }
+
+ fn extract_syscall_signature(&self, lines: &[&str], start: usize) -> String {
+ // Extract the full SYSCALL_DEFINE signature
+ let mut sig = String::new();
+ let mut in_paren = false;
+ let mut paren_count = 0;
+
+ for line in lines.iter().skip(start).take(20) {
+ let line = *line;
+
+ // Start of SYSCALL_DEFINE
+ if line.contains("SYSCALL_DEFINE") {
+ if let Some(pos) = line.find('(') {
+ sig.push_str(&line[pos..]);
+ in_paren = true;
+ paren_count = line[pos..].chars().filter(|&c| c == '(').count()
+ - line[pos..].chars().filter(|&c| c == ')').count();
+ }
+ } else if in_paren {
+ sig.push(' ');
+ sig.push_str(line.trim());
+ paren_count += line.chars().filter(|&c| c == '(').count();
+ paren_count =
+ paren_count.saturating_sub(line.chars().filter(|&c| c == ')').count());
+
+ if paren_count == 0 {
+ break;
+ }
+ }
+ }
+
+ sig
+ }
+}
+
+impl ApiExtractor for SourceExtractor {
+ fn extract_all(&self) -> Result<Vec<ApiSpec>> {
+ let path = Path::new(&self.path);
+ let mut all_specs = Vec::new();
+
+ if path.is_file() {
+ // Single file
+ all_specs.extend(self.extract_from_file(path)?);
+ } else if path.is_dir() {
+ // Directory - walk all .c files
+ for entry in WalkDir::new(path)
+ .into_iter()
+ .filter_map(|e| e.ok())
+ .filter(|e| {
+ e.path()
+ .extension()
+ .is_some_and(|ext| ext == "c" || ext == "h")
+ })
+ {
+ match self.extract_from_file(entry.path()) {
+ Ok(specs) => all_specs.extend(specs),
+ Err(e) => {
+ eprintln!("Warning: failed to parse {}: {}", entry.path().display(), e);
+ }
+ }
+ }
+ }
+
+ Ok(all_specs)
+ }
+
+ fn extract_by_name(&self, name: &str) -> Result<Option<ApiSpec>> {
+ let all_specs = self.extract_all()?;
+ Ok(all_specs.into_iter().find(|s| s.name == name))
+ }
+
+ fn display_api_details(
+ &self,
+ api_name: &str,
+ formatter: &mut dyn OutputFormatter,
+ output: &mut dyn Write,
+ ) -> Result<()> {
+ if let Some(spec) = self.extract_by_name(api_name)? {
+ display_api_spec(&spec, formatter, output)?;
+ } else {
+ writeln!(output, "API '{}' not found", api_name)?;
+ }
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn make_extractor() -> SourceExtractor {
+ SourceExtractor::new("/dev/null").unwrap()
+ }
+
+ #[test]
+ fn detect_contexts_spec() {
+ let content = r#"
+/**
+ * sys_foo - do foo
+ * @arg: the argument
+ *
+ * contexts: process, sleepable
+ *
+ * long-desc: Does foo.
+ */
+SYSCALL_DEFINE1(foo, int, arg)
+{
+ return 0;
+}
+
+/**
+ * bar - not a spec, even though the prose mentions context: here
+ * @x: value
+ */
+SYSCALL_DEFINE1(bar, int, x)
+{
+ return 0;
+}
+
+/**
+ * baz - not a spec either
+ * @x: value
+ *
+ * contexts: task, softirq, hardirq, nmi.
+ */
+SYSCALL_DEFINE1(baz, int, x)
+{
+ return 0;
+}
+"#;
+ let specs = make_extractor().extract_from_content(content).unwrap();
+ assert_eq!(specs.len(), 1);
+ assert_eq!(specs[0].name, "sys_foo");
+ }
+
+ #[test]
+ fn prose_mentioning_a_section_key_is_not_a_spec() {
+ let content = r#"
+/**
+ * __probe - check a device
+ * @drv: driver
+ *
+ * returns 0 on success, else error.
+ * side-effect: dev->driver is set to drv when drv claims dev.
+ */
+static int __probe(struct driver *drv, struct device *dev)
+{
+ return 0;
+}
+"#;
+ let specs = make_extractor().extract_from_content(content).unwrap();
+ assert!(specs.is_empty());
+ }
+
+ #[test]
+ fn nonexistent_path_is_rejected() {
+ let err = SourceExtractor::new("/nonexistent/kapi-test")
+ .err()
+ .unwrap();
+
+ assert!(err.to_string().contains("does not exist"), "{err}");
+ }
+
+ #[test]
+ fn has_context_line_needs_two_sections() {
+ let rule = SourceExtractor::has_context_line;
+
+ assert!(rule("contexts: process\nlong-desc: foo\n"));
+ assert!(rule("context-flags: KAPI_CTX_PROCESS\n lock: foo\n"));
+ assert!(rule("contexts: process\nparam: fd\n"));
+ assert!(rule("contexts: process\nerror: EINVAL, bad fd\n"));
+ assert!(!rule("contexts: process\n"));
+ assert!(!rule("context: process\nlong-desc: foo\n"));
+ assert!(!rule("long-desc: foo\nside-effect: bar\n"));
+ }
+
+ #[test]
+ fn detect_syscall_define3() {
+ let content = r#"
+/**
+ * sys_open - open a file
+ * context-flags: KAPI_CTX_PROCESS
+ * param-count: 3
+ * @filename: pathname to open
+ * param: filename
+ * error: ENOENT, test
+ */
+SYSCALL_DEFINE3(open, const char __user *, filename, int, flags, umode_t, mode)
+{
+ return 0;
+}
+"#;
+ let ext = make_extractor();
+ let specs = ext.extract_from_content(content).unwrap();
+ assert_eq!(specs.len(), 1);
+ assert_eq!(specs[0].name, "sys_open");
+ assert_eq!(specs[0].api_type, "syscall");
+ }
+
+ #[test]
+ fn detect_syscall_define1() {
+ let content = r#"
+/**
+ * sys_close - close a file descriptor
+ * context-flags: KAPI_CTX_PROCESS
+ * @fd: file descriptor to close
+ * error: EBADF, test
+ */
+SYSCALL_DEFINE1(close, unsigned int, fd)
+{
+ return 0;
+}
+"#;
+ let ext = make_extractor();
+ let specs = ext.extract_from_content(content).unwrap();
+ assert_eq!(specs.len(), 1);
+ assert_eq!(specs[0].name, "sys_close");
+ }
+
+ #[test]
+ fn detect_syscall_define6() {
+ let content = r#"
+/**
+ * sys_mmap - map memory
+ * context-flags: KAPI_CTX_PROCESS
+ * error: ENOMEM, test
+ */
+SYSCALL_DEFINE6(mmap, unsigned long, addr, unsigned long, len, unsigned long, prot,
+ unsigned long, flags, unsigned long, fd, unsigned long, offset)
+{
+ return 0;
+}
+"#;
+ let ext = make_extractor();
+ let specs = ext.extract_from_content(content).unwrap();
+ assert_eq!(specs.len(), 1);
+ assert_eq!(specs[0].name, "sys_mmap");
+ }
+
+ #[test]
+ fn detect_ioctl_pattern() {
+ let content = r#"
+/**
+ * my_ioctl - handle ioctl
+ * context-flags: KAPI_CTX_PROCESS
+ * error: EINVAL, test
+ */
+static long my_ioctl(struct file *filp, unsigned int cmd, unsigned long arg)
+{
+ return 0;
+}
+"#;
+ let ext = make_extractor();
+ let specs = ext.extract_from_content(content).unwrap();
+ assert_eq!(specs.len(), 1);
+ assert_eq!(specs[0].name, "my_ioctl");
+ assert_eq!(specs[0].api_type, "ioctl");
+ }
+
+ #[test]
+ fn find_function_after_skips_blanks() {
+ // Test that find_function_after looks past blank lines
+ let lines = vec!["", "", "SYSCALL_DEFINE2(foo, int, bar, int, baz)", "{"];
+ let ext = make_extractor();
+ let result = ext.find_function_after(&lines, 0);
+ assert!(result.is_some());
+ let (name, api_type, _sig) = result.unwrap();
+ assert_eq!(name, "sys_foo");
+ assert_eq!(api_type, "syscall");
+ }
+
+ #[test]
+ fn find_function_after_skips_plain_comment() {
+ let lines = vec![
+ "/*",
+ " * Careful here!",
+ " */",
+ "SYSCALL_DEFINE1(close, unsigned int, fd)",
+ "{",
+ ];
+ let ext = make_extractor();
+ let (name, api_type, _sig) = ext.find_function_after(&lines, 0).unwrap();
+ assert_eq!(name, "sys_close");
+ assert_eq!(api_type, "syscall");
+ }
+
+ #[test]
+ fn find_function_after_returns_none_for_no_match() {
+ // No function declaration within lookahead range
+ let lines = vec!["#include <linux/fs.h>", "#define FOO 1", "/* comment */"];
+ let ext = make_extractor();
+ let result = ext.find_function_after(&lines, 0);
+ assert!(result.is_none());
+ }
+
+ #[test]
+ fn find_function_after_detects_regular_function() {
+ let lines = vec!["", "int do_something(struct task_struct *task)", "{"];
+ let ext = make_extractor();
+ let result = ext.find_function_after(&lines, 0);
+ assert!(result.is_some());
+ let (name, api_type, _) = result.unwrap();
+ assert_eq!(name, "do_something");
+ assert_eq!(api_type, "function");
+ }
+
+ #[test]
+ fn no_kapi_annotations_produces_empty() {
+ // kerneldoc without any KAPI annotations should not produce a spec
+ let content = r#"
+/**
+ * my_func - does stuff
+ * @arg: an argument
+ */
+void my_func(int arg)
+{
+}
+"#;
+ let ext = make_extractor();
+ let specs = ext.extract_from_content(content).unwrap();
+ assert!(specs.is_empty());
+ }
+
+ #[test]
+ fn multiple_syscalls_in_one_file() {
+ let content = r#"
+/**
+ * sys_read - read from fd
+ * context-flags: KAPI_CTX_PROCESS
+ * error: EBADF, test
+ */
+SYSCALL_DEFINE3(read, unsigned int, fd, char __user *, buf, size_t, count)
+{
+ return 0;
+}
+
+/**
+ * sys_write - write to fd
+ * context-flags: KAPI_CTX_PROCESS
+ * error: EBADF, test
+ */
+SYSCALL_DEFINE3(write, unsigned int, fd, const char __user *, buf, size_t, count)
+{
+ return 0;
+}
+"#;
+ let ext = make_extractor();
+ let specs = ext.extract_from_content(content).unwrap();
+ assert_eq!(specs.len(), 2);
+ assert_eq!(specs[0].name, "sys_read");
+ assert_eq!(specs[1].name, "sys_write");
+ }
+}
--git a/tools/kapi/src/extractor/vmlinux/binary_utils.rs b/tools/kapi/src/extractor/vmlinux/binary_utils.rs
new file mode 100644
index 0000000000000..046772ea690c1
--- /dev/null
+++ b/tools/kapi/src/extractor/vmlinux/binary_utils.rs
@@ -0,0 +1,461 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+// Array-bound constants matching `include/linux/kernel_api_spec.h`.
+// String fields are `const char *`; call `DataReader::ptr_size()` for
+// the per-target pointer width.
+pub mod sizes {
+ pub const MAX_PARAMS: usize = 16;
+ pub const MAX_ERRORS: usize = 32;
+ pub const MAX_CONSTRAINTS: usize = 32;
+ pub const MAX_LOCKS: usize = 16;
+ pub const MAX_CAPABILITIES: usize = 8;
+ pub const MAX_SIGNALS: usize = 32;
+ pub const MAX_STRUCT_SPECS: usize = 8;
+ pub const MAX_SIDE_EFFECTS: usize = 32;
+ pub const MAX_STATE_TRANS: usize = 8;
+
+ pub const NAME: usize = 0;
+ pub const DESC: usize = 0;
+}
+
+// Section markers of `struct kernel_api_spec`. The kernel only sets a
+// marker when the matching *_COUNT()/KAPI_EXAMPLES() macro is used, so
+// a zero marker is as valid as the expected one.
+pub mod magic {
+ pub const PARAMS: u32 = 0x4B415031; // 'KAP1'
+ pub const RETURN: u32 = 0x4B415232; // 'KAR2'
+ pub const ERRORS: u32 = 0x4B414533; // 'KAE3'
+ pub const LOCKS: u32 = 0x4B414C34; // 'KAL4'
+ pub const CONSTRAINTS: u32 = 0x4B414335; // 'KAC5'
+ pub const INFO: u32 = 0x4B414936; // 'KAI6'
+ pub const SIGNALS: u32 = 0x4B415337; // 'KAS7'
+ pub const SIGMASK: u32 = 0x4B414D38; // 'KAM8'
+ pub const STRUCTS: u32 = 0x4B415439; // 'KAT9'
+ pub const EFFECTS: u32 = 0x4B414641; // 'KAFA'
+ pub const TRANS: u32 = 0x4B415442; // 'KATB'
+ pub const CAPS: u32 = 0x4B414343; // 'KACC'
+}
+
+/// Resolve a virtual-address string pointer against the vmlinux ELF
+/// and return the NUL-terminated C string it points at.
+pub fn resolve_vaddr_string(elf: &goblin::elf::Elf, data: &[u8], vaddr: u64) -> Option<String> {
+ if vaddr == 0 {
+ return None;
+ }
+ for sh in &elf.section_headers {
+ let start = sh.sh_addr;
+ let end = start.checked_add(sh.sh_size)?;
+ if vaddr < start || vaddr >= end {
+ continue;
+ }
+ // File-backed sections only (skip SHT_NOBITS etc.)
+ if sh.sh_type == goblin::elf::section_header::SHT_NOBITS {
+ return None;
+ }
+ let rel = (vaddr - start) as usize;
+ let file_start = sh.sh_offset as usize + rel;
+ if file_start >= data.len() {
+ return None;
+ }
+ let tail = &data[file_start..];
+ let nul = tail.iter().position(|&b| b == 0)?;
+ return std::str::from_utf8(&tail[..nul]).ok().map(str::to_string);
+ }
+ None
+}
+
+/// Endianness of the target ELF binary
+#[derive(Clone, Copy, PartialEq)]
+pub enum Endian {
+ Little,
+ Big,
+}
+
+/// Resolves string pointers read from `.kapi_specs` back to their
+/// underlying C strings in the vmlinux rodata.
+pub struct StringResolver<'a> {
+ pub elf: &'a goblin::elf::Elf<'a>,
+ pub vmlinux: &'a [u8],
+}
+
+// Helper for reading data at specific offsets
+pub struct DataReader<'a> {
+ pub data: &'a [u8],
+ pub pos: usize,
+ pub endian: Endian,
+ /// true for 64-bit ELF, false for 32-bit
+ pub is_64bit: bool,
+ /// Used to follow `const char *` fields into rodata.
+ pub resolver: Option<StringResolver<'a>>,
+}
+
+impl<'a> DataReader<'a> {
+ pub fn new(data: &'a [u8], offset: usize, endian: Endian, is_64bit: bool) -> Self {
+ Self {
+ data,
+ pos: offset,
+ endian,
+ is_64bit,
+ resolver: None,
+ }
+ }
+
+ pub fn with_resolver(mut self, resolver: StringResolver<'a>) -> Self {
+ self.resolver = Some(resolver);
+ self
+ }
+
+ /// Pointer width of the target in bytes (4 or 8).
+ pub fn ptr_size(&self) -> usize {
+ if self.is_64bit {
+ 8
+ } else {
+ 4
+ }
+ }
+
+ /// Advance the read position to the next multiple of `align`.
+ /// Needed before every naturally-aligned field when the containing
+ /// struct is not `__packed`.
+ pub fn align_to(&mut self, align: usize) {
+ if align > 1 {
+ let rem = self.pos % align;
+ if rem != 0 {
+ self.pos = (self.pos + (align - rem)).min(self.data.len());
+ }
+ }
+ }
+
+ /// Read a target-sized pointer slot. Returns the virtual address
+ /// stored in the slot, or `None` if there isn't enough data. The
+ /// caller is expected to align the reader first if the containing
+ /// struct demands natural alignment.
+ pub fn read_ptr(&mut self) -> Option<u64> {
+ self.align_to(self.ptr_size());
+ if self.is_64bit {
+ self.read_u64()
+ } else {
+ self.read_u32().map(|v| v as u64)
+ }
+ }
+
+ pub fn read_bytes(&mut self, len: usize) -> Option<&'a [u8]> {
+ if self.pos + len <= self.data.len() {
+ let bytes = &self.data[self.pos..self.pos + len];
+ self.pos += len;
+ Some(bytes)
+ } else {
+ None
+ }
+ }
+
+ pub fn read_u32(&mut self) -> Option<u32> {
+ self.align_to(4);
+ let b: [u8; 4] = self.read_bytes(4)?.try_into().unwrap();
+ Some(match self.endian {
+ Endian::Little => u32::from_le_bytes(b),
+ Endian::Big => u32::from_be_bytes(b),
+ })
+ }
+
+ pub fn read_u8(&mut self) -> Option<u8> {
+ self.read_bytes(1).map(|b| b[0])
+ }
+
+ pub fn read_i32(&mut self) -> Option<i32> {
+ self.align_to(4);
+ let b: [u8; 4] = self.read_bytes(4)?.try_into().unwrap();
+ Some(match self.endian {
+ Endian::Little => i32::from_le_bytes(b),
+ Endian::Big => i32::from_be_bytes(b),
+ })
+ }
+
+ pub fn read_u64(&mut self) -> Option<u64> {
+ self.align_to(8);
+ let b: [u8; 8] = self.read_bytes(8)?.try_into().unwrap();
+ Some(match self.endian {
+ Endian::Little => u64::from_le_bytes(b),
+ Endian::Big => u64::from_be_bytes(b),
+ })
+ }
+
+ pub fn read_i64(&mut self) -> Option<i64> {
+ self.align_to(8);
+ let b: [u8; 8] = self.read_bytes(8)?.try_into().unwrap();
+ Some(match self.endian {
+ Endian::Little => i64::from_le_bytes(b),
+ Endian::Big => i64::from_be_bytes(b),
+ })
+ }
+
+ /// Read a target-sized unsigned value (4 bytes for 32-bit, 8 bytes for 64-bit).
+ pub fn read_usize(&mut self) -> Option<usize> {
+ self.align_to(self.ptr_size());
+ if self.is_64bit {
+ // No double-align: read_u64 would re-align, but we just
+ // did that with ptr_size() which is 8 on 64-bit.
+ let b: [u8; 8] = self.read_bytes(8)?.try_into().unwrap();
+ Some(match self.endian {
+ Endian::Little => u64::from_le_bytes(b) as usize,
+ Endian::Big => u64::from_be_bytes(b) as usize,
+ })
+ } else {
+ let b: [u8; 4] = self.read_bytes(4)?.try_into().unwrap();
+ Some(match self.endian {
+ Endian::Little => u32::from_le_bytes(b) as usize,
+ Endian::Big => u32::from_be_bytes(b) as usize,
+ })
+ }
+ }
+
+ // Helper methods for common patterns
+ pub fn read_bool(&mut self) -> Option<bool> {
+ self.read_u8().map(|v| v != 0)
+ }
+
+ /// Read a `const char *` slot using the target pointer width
+ /// (4 bytes on 32-bit, 8 bytes on 64-bit) and, if a resolver is
+ /// attached, follow the address into the vmlinux to recover the
+ /// C string. The `_max_len` argument is ignored.
+ pub fn read_optional_string(&mut self, _max_len: usize) -> Option<String> {
+ let vaddr = self.read_ptr()?;
+ let resolver = self.resolver.as_ref()?;
+ resolve_vaddr_string(resolver.elf, resolver.vmlinux, vaddr).filter(|s| !s.is_empty())
+ }
+
+ pub fn read_string_or_default(&mut self, max_len: usize) -> String {
+ self.read_optional_string(max_len).unwrap_or_default()
+ }
+
+ /// Follow a `const s64 *` slot (already read with `read_ptr`) to the
+ /// `count` values it points at. A NULL or unresolvable pointer yields
+ /// an empty list.
+ pub fn resolve_s64_array(&self, vaddr: u64, count: u32) -> Vec<i64> {
+ let Some(resolver) = self.resolver.as_ref() else {
+ return Vec::new();
+ };
+ if vaddr == 0 {
+ return Vec::new();
+ }
+ let Some(start) = super::vaddr_to_file_offset(resolver.elf, vaddr) else {
+ return Vec::new();
+ };
+ let raw = (count as usize)
+ .checked_mul(8)
+ .and_then(|len| start.checked_add(len))
+ .and_then(|end| resolver.vmlinux.get(start..end));
+ raw.map_or_else(Vec::new, |raw| {
+ raw.chunks_exact(8)
+ .map(|chunk| {
+ let b: [u8; 8] = chunk.try_into().unwrap();
+ match self.endian {
+ Endian::Little => i64::from_le_bytes(b),
+ Endian::Big => i64::from_be_bytes(b),
+ }
+ })
+ .collect()
+ })
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ // ---- DataReader little-endian tests ----
+
+ #[test]
+ fn read_u32_little_endian() {
+ let data = [0x78, 0x56, 0x34, 0x12];
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_u32(), Some(0x12345678));
+ }
+
+ #[test]
+ fn read_u32_big_endian() {
+ let data = [0x12, 0x34, 0x56, 0x78];
+ let mut reader = DataReader::new(&data, 0, Endian::Big, true);
+ assert_eq!(reader.read_u32(), Some(0x12345678));
+ }
+
+ #[test]
+ fn read_u64_little_endian() {
+ let data = 0xDEADBEEFCAFEBABEu64.to_le_bytes();
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_u64(), Some(0xDEADBEEFCAFEBABE));
+ }
+
+ #[test]
+ fn read_u64_big_endian() {
+ let data = 0xDEADBEEFCAFEBABEu64.to_be_bytes();
+ let mut reader = DataReader::new(&data, 0, Endian::Big, true);
+ assert_eq!(reader.read_u64(), Some(0xDEADBEEFCAFEBABE));
+ }
+
+ #[test]
+ fn read_i32_little_endian_negative() {
+ let val: i32 = -42;
+ let data = val.to_le_bytes();
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_i32(), Some(-42));
+ }
+
+ #[test]
+ fn read_i32_big_endian_negative() {
+ let val: i32 = -1;
+ let data = val.to_be_bytes();
+ let mut reader = DataReader::new(&data, 0, Endian::Big, true);
+ assert_eq!(reader.read_i32(), Some(-1));
+ }
+
+ #[test]
+ fn read_i64_little_endian() {
+ let val: i64 = -9999999999;
+ let data = val.to_le_bytes();
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_i64(), Some(-9999999999));
+ }
+
+ #[test]
+ fn read_i64_big_endian() {
+ let val: i64 = i64::MIN;
+ let data = val.to_be_bytes();
+ let mut reader = DataReader::new(&data, 0, Endian::Big, true);
+ assert_eq!(reader.read_i64(), Some(i64::MIN));
+ }
+
+ // ---- read_usize tests ----
+
+ #[test]
+ fn read_usize_64bit() {
+ let val: u64 = 0x00000000FFFFFFFF;
+ let data = val.to_le_bytes();
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_usize(), Some(0xFFFFFFFF));
+ }
+
+ #[test]
+ fn read_usize_32bit() {
+ let val: u32 = 0xABCD1234;
+ let data = val.to_le_bytes();
+ let mut reader = DataReader::new(&data, 0, Endian::Little, false);
+ assert_eq!(reader.read_usize(), Some(0xABCD1234));
+ }
+
+ #[test]
+ fn read_usize_32bit_does_not_consume_8_bytes() {
+ // In 32-bit mode, read_usize should only consume 4 bytes
+ let mut data = [0u8; 8];
+ data[..4].copy_from_slice(&42u32.to_le_bytes());
+ data[4..8].copy_from_slice(&99u32.to_le_bytes());
+ let mut reader = DataReader::new(&data, 0, Endian::Little, false);
+ assert_eq!(reader.read_usize(), Some(42));
+ // After reading 4 bytes, pos should be at 4
+ assert_eq!(reader.pos, 4);
+ assert_eq!(reader.read_usize(), Some(99));
+ }
+
+ // ---- Bounds checking ----
+
+ #[test]
+ fn read_u32_past_end_returns_none() {
+ let data = [0x01, 0x02, 0x03]; // only 3 bytes, need 4
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_u32(), None);
+ }
+
+ #[test]
+ fn read_u64_past_end_returns_none() {
+ let data = [0u8; 7]; // only 7 bytes, need 8
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_u64(), None);
+ }
+
+ #[test]
+ fn read_bytes_past_end_returns_none() {
+ let data = [0u8; 4];
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_bytes(5), None);
+ }
+
+ #[test]
+ fn read_at_offset() {
+ // read_u32 auto-aligns to a 4-byte boundary, so the starting
+ // offset must itself be 4-aligned for the value to be read
+ // from its declared position.
+ let data = [0xFF, 0xFF, 0xFF, 0xFF, 0x78, 0x56, 0x34, 0x12];
+ let mut reader = DataReader::new(&data, 4, Endian::Little, true);
+ assert_eq!(reader.read_u32(), Some(0x12345678));
+ }
+
+ #[test]
+ fn read_u32_auto_aligns() {
+ // Starting mid-word, read_u32 snaps to the next 4-byte boundary.
+ let data = [0xDE, 0xAD, 0xBE, 0xEF, 0x78, 0x56, 0x34, 0x12];
+ let mut reader = DataReader::new(&data, 1, Endian::Little, true);
+ assert_eq!(reader.read_u32(), Some(0x12345678));
+ assert_eq!(reader.pos, 8);
+ }
+
+ #[test]
+ fn read_ptr_32bit_uses_4_bytes() {
+ let data = [0x78, 0x56, 0x34, 0x12];
+ let mut reader = DataReader::new(&data, 0, Endian::Little, false);
+ assert_eq!(reader.read_ptr(), Some(0x12345678));
+ assert_eq!(reader.pos, 4);
+ }
+
+ #[test]
+ fn read_ptr_64bit_uses_8_bytes() {
+ let data = [0x78, 0x56, 0x34, 0x12, 0x00, 0x00, 0x00, 0x00];
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_ptr(), Some(0x12345678));
+ assert_eq!(reader.pos, 8);
+ }
+
+ #[test]
+ fn read_bool_values() {
+ let data = [0, 1, 255];
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_bool(), Some(false));
+ assert_eq!(reader.read_bool(), Some(true));
+ assert_eq!(reader.read_bool(), Some(true)); // any non-zero is true
+ }
+
+ #[test]
+ fn sequential_reads_advance_position() {
+ let mut data = [0u8; 12];
+ data[..4].copy_from_slice(&1u32.to_le_bytes());
+ data[4..8].copy_from_slice(&2u32.to_le_bytes());
+ data[8..12].copy_from_slice(&3u32.to_le_bytes());
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_u32(), Some(1));
+ assert_eq!(reader.read_u32(), Some(2));
+ assert_eq!(reader.read_u32(), Some(3));
+ assert_eq!(reader.pos, 12);
+ }
+
+ #[test]
+ fn read_optional_string_empty_returns_none() {
+ // A string buffer that is just NUL
+ let data = [0u8; 10];
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_optional_string(10), None);
+ }
+
+ #[test]
+ fn read_string_or_default_with_empty() {
+ let data = [0u8; 10];
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_string_or_default(10), "");
+ }
+
+ #[test]
+ fn read_u8_value() {
+ let data = [0x42];
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+ assert_eq!(reader.read_u8(), Some(0x42));
+ }
+}
--git a/tools/kapi/src/extractor/vmlinux/mod.rs b/tools/kapi/src/extractor/vmlinux/mod.rs
new file mode 100644
index 0000000000000..5202f7d80c8d8
--- /dev/null
+++ b/tools/kapi/src/extractor/vmlinux/mod.rs
@@ -0,0 +1,1160 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+use super::{
+ ApiExtractor, ApiSpec, CapabilitySpec, ConstraintSpec, ErrorSpec, LockSpec, ParamSpec,
+ ReturnSpec, SideEffectSpec, SignalMaskSpec, SignalSpec, StateTransitionSpec, StructFieldSpec,
+ StructSpec,
+};
+use crate::formatter::OutputFormatter;
+use anyhow::{Context, Result};
+use goblin::elf::Elf;
+use std::fs;
+use std::io::Write;
+
+mod binary_utils;
+use binary_utils::{magic, sizes, DataReader, Endian};
+
+// Helper to convert empty strings to None
+fn opt_string(s: String) -> Option<String> {
+ if s.is_empty() {
+ None
+ } else {
+ Some(s)
+ }
+}
+
+pub struct VmlinuxExtractor {
+ vmlinux: Vec<u8>,
+ specs: Vec<KapiSpec>,
+ endian: Endian,
+ is_64bit: bool,
+}
+
+#[derive(Debug)]
+struct KapiSpec {
+ name: String,
+ api_type: String,
+ /// File offset in the vmlinux buffer where this spec's
+ /// `struct kernel_api_spec` begins.
+ file_offset: usize,
+}
+
+impl VmlinuxExtractor {
+ pub fn new(vmlinux_path: &str) -> Result<Self> {
+ let vmlinux = fs::read(vmlinux_path)
+ .with_context(|| format!("Failed to read vmlinux file: {vmlinux_path}"))?;
+
+ let elf = Elf::parse(&vmlinux).context("Failed to parse ELF file")?;
+ let endian = if elf.little_endian {
+ Endian::Little
+ } else {
+ Endian::Big
+ };
+ let is_64bit = elf.is_64;
+
+ // Locate the .kapi_specs section boundaries.
+ let mut start_addr = None;
+ let mut stop_addr = None;
+ for sym in &elf.syms {
+ if let Some(name) = elf.strtab.get_at(sym.st_name) {
+ match name {
+ "__start_kapi_specs" => start_addr = Some(sym.st_value),
+ "__stop_kapi_specs" => stop_addr = Some(sym.st_value),
+ _ => {}
+ }
+ }
+ }
+ let start = start_addr.context("Could not find __start_kapi_specs symbol")?;
+ let stop = stop_addr.context("Could not find __stop_kapi_specs symbol")?;
+ if stop <= start {
+ anyhow::bail!("No kernel API specifications found in vmlinux");
+ }
+
+ // `.kapi_specs` is a tightly-packed array of `struct kernel_api_spec *`
+ // pointers; walk them to find each real spec's vaddr, then resolve to
+ // a file offset inside `vmlinux`. Pointer width tracks the target
+ // (4 bytes for 32-bit, 8 bytes for 64-bit).
+ let ptr_size = if is_64bit { 8usize } else { 4 };
+ let ptr_count = ((stop - start) as usize) / ptr_size;
+ let ptr_file_off =
+ vaddr_to_file_offset(&elf, start).context("Could not locate .kapi_specs in file")?;
+
+ let read_ptr = |raw: &[u8]| -> u64 {
+ match (endian, is_64bit) {
+ (Endian::Little, true) => u64::from_le_bytes(raw.try_into().unwrap()),
+ (Endian::Big, true) => u64::from_be_bytes(raw.try_into().unwrap()),
+ (Endian::Little, false) => u32::from_le_bytes(raw.try_into().unwrap()) as u64,
+ (Endian::Big, false) => u32::from_be_bytes(raw.try_into().unwrap()) as u64,
+ }
+ };
+
+ let mut specs = Vec::with_capacity(ptr_count);
+ for i in 0..ptr_count {
+ let p = ptr_file_off + i * ptr_size;
+ if p + ptr_size > vmlinux.len() {
+ break;
+ }
+ let spec_vaddr = read_ptr(&vmlinux[p..p + ptr_size]);
+ if spec_vaddr == 0 {
+ continue;
+ }
+ let Some(spec_file_off) = vaddr_to_file_offset(&elf, spec_vaddr) else {
+ continue;
+ };
+ // The first field of `struct kernel_api_spec` is `const char *name`.
+ if spec_file_off + ptr_size > vmlinux.len() {
+ continue;
+ }
+ let name_vaddr = read_ptr(&vmlinux[spec_file_off..spec_file_off + ptr_size]);
+ let name =
+ binary_utils::resolve_vaddr_string(&elf, &vmlinux, name_vaddr).unwrap_or_default();
+ if name.is_empty() {
+ continue;
+ }
+ let api_type = if name.starts_with("sys_") {
+ "syscall"
+ } else if name.ends_with("_ioctl") {
+ "ioctl"
+ } else {
+ "function"
+ }
+ .to_string();
+ specs.push(KapiSpec {
+ name,
+ api_type,
+ file_offset: spec_file_off,
+ });
+ }
+
+ Ok(VmlinuxExtractor {
+ vmlinux,
+ specs,
+ endian,
+ is_64bit,
+ })
+ }
+}
+
+/// Map a virtual address to a file offset inside the raw vmlinux bytes.
+fn vaddr_to_file_offset(elf: &Elf, vaddr: u64) -> Option<usize> {
+ for sh in &elf.section_headers {
+ let start = sh.sh_addr;
+ let end = start.checked_add(sh.sh_size)?;
+ if vaddr >= start && vaddr < end {
+ if sh.sh_type == goblin::elf::section_header::SHT_NOBITS {
+ return None;
+ }
+ return Some((sh.sh_offset + (vaddr - start)) as usize);
+ }
+ }
+ None
+}
+
+impl VmlinuxExtractor {
+ fn parse_at(&self, file_offset: usize) -> Result<ApiSpec> {
+ parse_binary_to_api_spec(&self.vmlinux, file_offset, self.endian, self.is_64bit)
+ }
+}
+
+impl ApiExtractor for VmlinuxExtractor {
+ fn extract_all(&self) -> Result<Vec<ApiSpec>> {
+ Ok(self
+ .specs
+ .iter()
+ .map(|spec| {
+ self.parse_at(spec.file_offset).unwrap_or_else(|e| {
+ eprintln!("Warning: cannot parse the spec of {}: {e:#}", spec.name);
+ ApiSpec {
+ name: spec.name.clone(),
+ api_type: spec.api_type.clone(),
+ ..Default::default()
+ }
+ })
+ })
+ .collect())
+ }
+
+ fn extract_by_name(&self, api_name: &str) -> Result<Option<ApiSpec>> {
+ if let Some(spec) = self.specs.iter().find(|s| s.name == api_name) {
+ Ok(Some(self.parse_at(spec.file_offset)?))
+ } else {
+ Ok(None)
+ }
+ }
+
+ fn display_api_details(
+ &self,
+ api_name: &str,
+ formatter: &mut dyn OutputFormatter,
+ writer: &mut dyn Write,
+ ) -> Result<()> {
+ if let Some(spec) = self.specs.iter().find(|s| s.name == api_name) {
+ let api_spec = self.parse_at(spec.file_offset)?;
+ super::display_api_spec(&api_spec, formatter, writer)?;
+ }
+ Ok(())
+ }
+}
+
+const TRUNCATED: &str = "kernel_api_spec runs past the end of the file";
+
+/// Consume a section marker. The kernel leaves it zero when the matching
+/// macro is not used, so only a different non-zero value means that the
+/// reader has lost sync with the struct layout.
+fn read_magic(reader: &mut DataReader, expected: u32) -> Result<()> {
+ let found = reader.read_u32().context(TRUNCATED)?;
+ if found != 0 && found != expected {
+ anyhow::bail!(
+ "unexpected section marker {found:#x} at offset {:#x}, expected {expected:#x}",
+ reader.pos - 4
+ );
+ }
+ Ok(())
+}
+
+/// Parse a `{ u32 magic; u32 count; T items[MAX]; }` section. Every one of
+/// the `max_items` slots is consumed, so the reader ends up behind the
+/// whole array; only the first `count` are returned.
+fn parse_array<T, F>(
+ reader: &mut DataReader,
+ expected_magic: u32,
+ max_items: usize,
+ parse_fn: F,
+) -> Result<Vec<T>>
+where
+ F: Fn(&mut DataReader, usize) -> Option<T>,
+{
+ read_magic(reader, expected_magic)?;
+ let count = reader.read_u32().context(TRUNCATED)? as usize;
+ let align = reader.ptr_size();
+ reader.align_to(align);
+
+ let mut items = Vec::new();
+ for i in 0..max_items {
+ let item = parse_fn(reader, i).context(TRUNCATED)?;
+ reader.align_to(align);
+ if i < count {
+ items.push(item);
+ }
+ }
+ Ok(items)
+}
+
+fn parse_binary_to_api_spec(
+ data: &[u8],
+ offset: usize,
+ endian: Endian,
+ is_64bit: bool,
+) -> Result<ApiSpec> {
+ let elf = Elf::parse(data).context("Failed to re-parse ELF for string resolution")?;
+ let resolver = binary_utils::StringResolver {
+ elf: &elf,
+ vmlinux: data,
+ };
+ let mut reader = DataReader::new(data, offset, endian, is_64bit).with_resolver(resolver);
+
+ // Read fields in exact order of struct kernel_api_spec.
+ // Every string field is a `const char *` pointer resolved via the
+ // StringResolver attached to the DataReader.
+ let name = reader
+ .read_optional_string(sizes::NAME)
+ .ok_or_else(|| anyhow::anyhow!("Failed to read API name"))?;
+
+ // Determine API type
+ let api_type = if name.starts_with("sys_") {
+ "syscall"
+ } else if name.ends_with("_ioctl") {
+ "ioctl"
+ } else if name.contains("sysfs") {
+ "sysfs"
+ } else {
+ "function"
+ }
+ .to_string();
+
+ let version = reader.read_u32().map(|v| v.to_string());
+
+ let description = reader
+ .read_optional_string(sizes::DESC)
+ .filter(|s| !s.is_empty());
+
+ let long_description = reader
+ .read_optional_string(sizes::DESC)
+ .filter(|s| !s.is_empty());
+
+ let context_flags = parse_context_flags(&mut reader);
+
+ let parameters = parse_array(&mut reader, magic::PARAMS, sizes::MAX_PARAMS, parse_param)?;
+
+ read_magic(&mut reader, magic::RETURN)?;
+ let return_spec = parse_return_spec(&mut reader);
+
+ let errors = parse_array(&mut reader, magic::ERRORS, sizes::MAX_ERRORS, |r, _| {
+ parse_error(r)
+ })?;
+
+ let locks = parse_array(&mut reader, magic::LOCKS, sizes::MAX_LOCKS, |r, _| {
+ parse_lock(r)
+ })?;
+
+ let constraints = parse_array(
+ &mut reader,
+ magic::CONSTRAINTS,
+ sizes::MAX_CONSTRAINTS,
+ |r, _| parse_constraint(r),
+ )?;
+
+ // Only KAPI_EXAMPLES() sets info_magic, so it says nothing about
+ // whether notes are present.
+ read_magic(&mut reader, magic::INFO)?;
+ let examples = reader
+ .read_optional_string(sizes::DESC)
+ .filter(|s| !s.is_empty());
+ let notes = reader
+ .read_optional_string(sizes::DESC)
+ .filter(|s| !s.is_empty());
+
+ let signals = parse_array(&mut reader, magic::SIGNALS, sizes::MAX_SIGNALS, |r, _| {
+ parse_signal(r)
+ })?;
+
+ let signal_masks = parse_array(&mut reader, magic::SIGMASK, sizes::MAX_SIGNALS, |r, _| {
+ parse_signal_mask(r)
+ })?;
+
+ let struct_specs = parse_array(
+ &mut reader,
+ magic::STRUCTS,
+ sizes::MAX_STRUCT_SPECS,
+ |r, _| parse_struct_spec(r),
+ )?;
+
+ let side_effects = parse_array(
+ &mut reader,
+ magic::EFFECTS,
+ sizes::MAX_SIDE_EFFECTS,
+ |r, _| parse_side_effect(r),
+ )?;
+
+ let state_transitions =
+ parse_array(&mut reader, magic::TRANS, sizes::MAX_STATE_TRANS, |r, _| {
+ parse_state_transition(r)
+ })?;
+
+ let capabilities = parse_array(&mut reader, magic::CAPS, sizes::MAX_CAPABILITIES, |r, _| {
+ parse_capability(r)
+ })?;
+
+ Ok(ApiSpec {
+ name,
+ api_type,
+ description,
+ long_description,
+ version,
+ context_flags,
+ param_count: if parameters.is_empty() {
+ None
+ } else {
+ Some(parameters.len() as u32)
+ },
+ error_count: if errors.is_empty() {
+ None
+ } else {
+ Some(errors.len() as u32)
+ },
+ examples,
+ notes,
+ subsystem: None,
+ sysfs_path: None,
+ permissions: None,
+ capabilities,
+ parameters,
+ return_spec,
+ errors,
+ signals,
+ signal_masks,
+ side_effects,
+ state_transitions,
+ constraints,
+ locks,
+ struct_specs,
+ })
+}
+
+// Helper parsing functions
+
+fn parse_context_flags(reader: &mut DataReader) -> Vec<String> {
+ const KAPI_CTX_PROCESS: u32 = 1 << 0;
+ const KAPI_CTX_SOFTIRQ: u32 = 1 << 1;
+ const KAPI_CTX_HARDIRQ: u32 = 1 << 2;
+ const KAPI_CTX_NMI: u32 = 1 << 3;
+ const KAPI_CTX_ATOMIC: u32 = 1 << 4;
+ const KAPI_CTX_SLEEPABLE: u32 = 1 << 5;
+ const KAPI_CTX_PREEMPT_DISABLED: u32 = 1 << 6;
+ const KAPI_CTX_IRQ_DISABLED: u32 = 1 << 7;
+
+ if let Some(flags) = reader.read_u32() {
+ let mut parts = Vec::new();
+
+ if flags & KAPI_CTX_PROCESS != 0 {
+ parts.push("KAPI_CTX_PROCESS");
+ }
+ if flags & KAPI_CTX_SOFTIRQ != 0 {
+ parts.push("KAPI_CTX_SOFTIRQ");
+ }
+ if flags & KAPI_CTX_HARDIRQ != 0 {
+ parts.push("KAPI_CTX_HARDIRQ");
+ }
+ if flags & KAPI_CTX_NMI != 0 {
+ parts.push("KAPI_CTX_NMI");
+ }
+ if flags & KAPI_CTX_ATOMIC != 0 {
+ parts.push("KAPI_CTX_ATOMIC");
+ }
+ if flags & KAPI_CTX_SLEEPABLE != 0 {
+ parts.push("KAPI_CTX_SLEEPABLE");
+ }
+ if flags & KAPI_CTX_PREEMPT_DISABLED != 0 {
+ parts.push("KAPI_CTX_PREEMPT_DISABLED");
+ }
+ if flags & KAPI_CTX_IRQ_DISABLED != 0 {
+ parts.push("KAPI_CTX_IRQ_DISABLED");
+ }
+
+ parts.into_iter().map(|s| s.to_string()).collect()
+ } else {
+ vec![]
+ }
+}
+
+fn parse_param(reader: &mut DataReader, index: usize) -> Option<ParamSpec> {
+ let name = reader.read_string_or_default(sizes::NAME);
+ let type_name = reader.read_string_or_default(sizes::NAME);
+ let param_type = reader.read_u32()?;
+ let flags = reader.read_u32()?;
+ let size = reader.read_usize()?;
+ let alignment = reader.read_usize()?;
+ let min_value = reader.read_i64()?;
+ let max_value = reader.read_i64()?;
+ let valid_mask = reader.read_u64()?;
+
+ let enum_values_ptr = reader.read_ptr()?;
+ let enum_count = reader.read_u32()?;
+ let constraint_type = reader.read_u32()?;
+ // Skip validate function pointer
+ reader.read_ptr()?;
+
+ let description = reader.read_string_or_default(sizes::DESC);
+ let constraint = reader.read_optional_string(sizes::DESC);
+ let size_param_idx_raw = reader.read_i32()?; // Must use ? to propagate errors
+ let _size_multiplier = reader.read_usize()?; // Must use ? to propagate errors
+
+ // In the C struct, size_param_idx is stored 1-based; 0 means
+ // "no size-carrying param". Surface the real (0-based) index as
+ // `Option<u32>`.
+ let size_param_idx = if size_param_idx_raw > 0 {
+ Some((size_param_idx_raw - 1) as u32)
+ } else {
+ None
+ };
+
+ let mut param = ParamSpec {
+ index: index as u32,
+ name,
+ type_name,
+ description,
+ flags,
+ param_type,
+ constraint_type,
+ constraint,
+ min_value: Some(min_value),
+ max_value: Some(max_value),
+ valid_mask: Some(valid_mask),
+ enum_values: reader
+ .resolve_s64_array(enum_values_ptr, enum_count)
+ .iter()
+ .map(i64::to_string)
+ .collect(),
+ size: Some(size as u32),
+ alignment: Some(alignment as u32),
+ size_param_idx,
+ };
+ param.keep_used_numbers();
+ Some(param)
+}
+
+fn parse_return_spec(reader: &mut DataReader) -> Option<ReturnSpec> {
+ // Read type_name, but treat empty as valid (will be empty string)
+ let type_name = reader.read_string_or_default(sizes::NAME);
+
+ // Read return_type and check_type
+ let return_type = reader.read_u32().unwrap_or(0);
+ let check_type = reader.read_u32().unwrap_or(0);
+ let success_value = reader.read_i64().unwrap_or(0);
+ let success_min = reader.read_i64().unwrap_or(0);
+ let success_max = reader.read_i64().unwrap_or(0);
+
+ let error_values_ptr = reader.read_ptr().unwrap_or(0);
+ let error_count = reader.read_u32().unwrap_or(0);
+ // Skip is_success function pointer
+ let _ = reader.read_ptr();
+
+ let description = reader.read_string_or_default(sizes::DESC);
+
+ // Return a spec even if type_name is empty, as long as we have some data
+ // The type_name might be a string like "KAPI_TYPE_INT" that gets stored literally
+ if type_name.is_empty() && return_type == 0 && check_type == 0 && success_value == 0 {
+ // No return spec at all
+ return None;
+ }
+
+ let mut ret = ReturnSpec {
+ type_name,
+ description,
+ return_type,
+ check_type,
+ success_value: Some(success_value),
+ success_min: Some(success_min),
+ success_max: Some(success_max),
+ error_values: reader
+ .resolve_s64_array(error_values_ptr, error_count)
+ .into_iter()
+ .filter_map(|v| i32::try_from(v).ok())
+ .collect(),
+ };
+ ret.keep_used_success_fields();
+ Some(ret)
+}
+
+fn parse_error(reader: &mut DataReader) -> Option<ErrorSpec> {
+ let error_code = reader.read_i32()?;
+ let name = reader.read_string_or_default(sizes::NAME);
+ let condition = reader.read_string_or_default(sizes::DESC);
+ let description = reader.read_string_or_default(sizes::DESC);
+
+ Some(ErrorSpec {
+ error_code,
+ name,
+ condition,
+ description,
+ })
+}
+
+fn parse_lock(reader: &mut DataReader) -> Option<LockSpec> {
+ let lock_name = reader.read_string_or_default(sizes::NAME);
+ let lock_type = reader.read_u32()?;
+ let scope = reader.read_u32()?;
+ let description = reader.read_string_or_default(sizes::DESC);
+
+ Some(LockSpec {
+ lock_name,
+ lock_type,
+ scope,
+ description,
+ })
+}
+
+fn parse_constraint(reader: &mut DataReader) -> Option<ConstraintSpec> {
+ let name = reader.read_string_or_default(sizes::NAME);
+ let description = reader.read_string_or_default(sizes::DESC);
+ let expression = reader.read_string_or_default(sizes::DESC);
+
+ Some(ConstraintSpec {
+ name,
+ description,
+ expression: opt_string(expression),
+ })
+}
+
+fn parse_signal(reader: &mut DataReader) -> Option<SignalSpec> {
+ // Matches `struct kapi_signal_spec`. All string fields are pointers.
+ let signal_num = reader.read_i32()?;
+ let signal_name = reader.read_optional_string(sizes::NAME).unwrap_or_default();
+ let direction = reader.read_u32()?;
+ let action = reader.read_u32()?;
+ let target = reader.read_optional_string(sizes::DESC);
+ let condition = reader.read_optional_string(sizes::DESC);
+ let description = reader.read_optional_string(sizes::DESC);
+ let restartable = reader.read_bool()?;
+ let sa_flags_required = reader.read_u32()?;
+ let sa_flags_forbidden = reader.read_u32()?;
+ let error_on_signal = reader.read_i32()?;
+ let transform_to = reader.read_i32()?;
+ // Read the symbolic timing token (const char *) and map it to the
+ // numeric timing code used by downstream consumers.
+ let timing_str = reader.read_optional_string(sizes::NAME).unwrap_or_default();
+ let timing = match timing_str.as_str() {
+ "KAPI_SIGNAL_TIME_BEFORE" | "before" => 0u32,
+ "KAPI_SIGNAL_TIME_DURING" | "during" => 1,
+ "KAPI_SIGNAL_TIME_AFTER" | "after" => 2,
+ _ => 0,
+ };
+ let priority = reader.read_u8()?;
+ let interruptible = reader.read_bool()?;
+ let queue_behavior = reader.read_optional_string(sizes::NAME);
+ let state_required = reader.read_u32()?;
+ let state_forbidden = reader.read_u32()?;
+
+ Some(SignalSpec {
+ signal_num,
+ signal_name,
+ direction,
+ action,
+ target,
+ condition,
+ description,
+ timing,
+ priority: priority as u32,
+ restartable,
+ interruptible,
+ queue: queue_behavior,
+ sa_flags: 0, // Not a field of struct kapi_signal_spec
+ sa_flags_required,
+ sa_flags_forbidden,
+ state_required,
+ state_forbidden,
+ // `error_on_signal` of 0 means "no errno returned"; surface
+ // that as None to match the source-parser convention.
+ error_on_signal: if error_on_signal != 0 {
+ Some(error_on_signal)
+ } else {
+ None
+ },
+ transform_to: if transform_to != 0 {
+ // The compiled struct holds the numeric value; the C
+ // preprocessor already resolved any signal symbol.
+ Some(transform_to)
+ } else {
+ None
+ },
+ })
+}
+
+fn parse_signal_mask(reader: &mut DataReader) -> Option<SignalMaskSpec> {
+ let name = reader.read_string_or_default(sizes::NAME);
+
+ let mut signals = Vec::with_capacity(sizes::MAX_SIGNALS);
+ for _ in 0..sizes::MAX_SIGNALS {
+ signals.push(reader.read_i32()?);
+ }
+ let signal_count = reader.read_u32()?;
+ signals.truncate(signal_count as usize);
+
+ let description = reader.read_string_or_default(sizes::DESC);
+
+ Some(SignalMaskSpec {
+ name,
+ description,
+ signals,
+ })
+}
+
+fn parse_struct_field(reader: &mut DataReader) -> Option<StructFieldSpec> {
+ let name = reader.read_string_or_default(sizes::NAME);
+ let field_type = reader.read_u32()?;
+ let type_name = reader.read_string_or_default(sizes::NAME);
+ let offset = reader.read_usize()?;
+ let size = reader.read_usize()?;
+ let flags = reader.read_u32()?;
+ let constraint_type = reader.read_u32()?;
+ let min_value = reader.read_i64()?;
+ let max_value = reader.read_i64()?;
+ let valid_mask = reader.read_u64()?;
+ // enum_values is a `const char *` that StructFieldSpec has no slot for
+ reader.read_ptr()?;
+ let description = reader.read_string_or_default(sizes::DESC);
+
+ Some(StructFieldSpec {
+ name,
+ field_type,
+ type_name,
+ offset,
+ size,
+ flags,
+ constraint_type,
+ min_value,
+ max_value,
+ valid_mask,
+ description,
+ })
+}
+
+fn parse_struct_spec(reader: &mut DataReader) -> Option<StructSpec> {
+ let name = reader.read_string_or_default(sizes::NAME);
+ let size = reader.read_usize()?;
+ let alignment = reader.read_usize()?;
+ let field_count = reader.read_u32()?;
+
+ let mut fields = Vec::new();
+ for i in 0..sizes::MAX_PARAMS {
+ let field = parse_struct_field(reader)?;
+ reader.align_to(reader.ptr_size());
+ if i < field_count as usize {
+ fields.push(field);
+ }
+ }
+
+ let description = reader.read_string_or_default(sizes::DESC);
+
+ Some(StructSpec {
+ name,
+ size,
+ alignment,
+ field_count: fields.len() as u32,
+ fields,
+ description,
+ })
+}
+
+fn parse_side_effect(reader: &mut DataReader) -> Option<SideEffectSpec> {
+ let effect_type = reader.read_u32()?;
+ let target = reader.read_string_or_default(sizes::NAME);
+ let condition = reader.read_string_or_default(sizes::DESC);
+ let description = reader.read_string_or_default(sizes::DESC);
+ let reversible = reader.read_bool()?;
+
+ Some(SideEffectSpec {
+ effect_type,
+ target,
+ condition: opt_string(condition),
+ description,
+ reversible,
+ })
+}
+
+fn parse_state_transition(reader: &mut DataReader) -> Option<StateTransitionSpec> {
+ let from_state = reader.read_string_or_default(sizes::NAME);
+ let to_state = reader.read_string_or_default(sizes::NAME);
+ let condition = reader.read_string_or_default(sizes::DESC);
+ let object = reader.read_string_or_default(sizes::NAME);
+ let description = reader.read_string_or_default(sizes::DESC);
+
+ Some(StateTransitionSpec {
+ object,
+ from_state,
+ to_state,
+ condition: opt_string(condition),
+ description,
+ })
+}
+
+fn parse_capability(reader: &mut DataReader) -> Option<CapabilitySpec> {
+ // Struct layout matches `struct kapi_capability_spec`:
+ // int capability; const char *cap_name; enum action;
+ // const char *allows; const char *without_cap;
+ // const char *check_condition; u8 priority;
+ // int alternative[KAPI_MAX_CAPABILITIES]; u32 alternative_count;
+ let capability = reader.read_i32()?;
+ let cap_name = reader.read_string_or_default(sizes::NAME);
+ let action = reader.read_u32()?;
+ let allows = reader.read_string_or_default(sizes::DESC);
+ let without_cap = reader.read_string_or_default(sizes::DESC);
+ let check_condition = reader.read_optional_string(sizes::DESC);
+ let priority = reader.read_u8()?;
+
+ let mut alternatives = Vec::with_capacity(sizes::MAX_CAPABILITIES);
+ for _ in 0..sizes::MAX_CAPABILITIES {
+ alternatives.push(reader.read_i32()?);
+ }
+ let alternative_count = reader.read_u32()?;
+ alternatives.truncate(alternative_count as usize);
+
+ Some(CapabilitySpec {
+ capability,
+ name: cap_name,
+ action: capability_action_to_string(action),
+ allows,
+ without_cap,
+ check_condition,
+ priority: Some(priority),
+ alternatives,
+ })
+}
+
+/// Map the `enum kapi_capability_action` numeric value to its symbolic
+/// spelling, matching `include/linux/kernel_api_spec.h`.
+fn capability_action_to_string(n: u32) -> String {
+ match n {
+ 0 => "KAPI_CAP_BYPASS_CHECK",
+ 1 => "KAPI_CAP_INCREASE_LIMIT",
+ 2 => "KAPI_CAP_OVERRIDE_RESTRICTION",
+ 3 => "KAPI_CAP_GRANT_PERMISSION",
+ 4 => "KAPI_CAP_MODIFY_BEHAVIOR",
+ 5 => "KAPI_CAP_ACCESS_RESOURCE",
+ 6 => "KAPI_CAP_PERFORM_OPERATION",
+ _ => return n.to_string(),
+ }
+ .to_string()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn state_transition_with_empty_strings_consumes_the_whole_struct() {
+ // five `const char *` slots: from_state, to_state, condition,
+ // object, description
+ let data = [0u8; 5 * 8];
+ let mut reader = DataReader::new(&data, 0, Endian::Little, true);
+
+ let trans = parse_state_transition(&mut reader).unwrap();
+
+ assert_eq!(reader.pos, data.len());
+ assert_eq!(trans.from_state, "");
+ assert_eq!(trans.condition, None);
+ assert_eq!(trans.description, "");
+ }
+
+ // Offsets inside `struct kernel_api_spec` and its element structs as
+ // laid out by gcc on x86-64, taken from offsetof()/sizeof().
+ const SPEC_SIZE: usize = 26400;
+ const PARAM_MAGIC: usize = 36;
+ const PARAMS: usize = 48;
+ const PARAM_SIZE: usize = 120;
+ const RETURN_MAGIC: usize = 1968;
+ const RETURN_SPEC: usize = 1976;
+ const ERROR_MAGIC: usize = 2048;
+ const ERRORS: usize = 2056;
+ const ERROR_SIZE: usize = 32;
+ const LOCK_MAGIC: usize = 3080;
+ const LOCKS: usize = 3088;
+ const LOCK_SIZE: usize = 24;
+ const CONSTRAINT_MAGIC: usize = 3472;
+ const CONSTRAINTS: usize = 3480;
+ const CONSTRAINT_SIZE: usize = 24;
+ const INFO_MAGIC: usize = 4248;
+ const NOTES: usize = 4264;
+ const SIGNAL_MAGIC: usize = 4272;
+ const SIGNALS: usize = 4280;
+ const SIGNAL_SIZE: usize = 104;
+ const SIGMASK_MAGIC: usize = 7608;
+ const SIGNAL_MASKS: usize = 7616;
+ const SIGNAL_MASK_SIZE: usize = 152;
+ const STRUCT_MAGIC: usize = 12480;
+ const STRUCT_SPECS: usize = 12488;
+ const STRUCT_SPEC_SIZE: usize = 1448;
+ const STRUCT_FIELD_SIZE: usize = 88;
+ const EFFECT_MAGIC: usize = 24072;
+ const SIDE_EFFECTS: usize = 24080;
+ const SIDE_EFFECT_SIZE: usize = 40;
+ const TRANS_MAGIC: usize = 25360;
+ const STATE_TRANSITIONS: usize = 25368;
+ const STATE_TRANSITION_SIZE: usize = 40;
+ const CAP_MAGIC: usize = 25688;
+ const CAPABILITIES: usize = 25696;
+ const CAPABILITY_SIZE: usize = 88;
+
+ const BASE: u64 = 0xffff_ffff_8100_0000;
+ const CONTENT_OFFSET: usize = 0x1000;
+
+ /// A `struct kernel_api_spec` image preceded by the strings and
+ /// `s64` arrays it points at, wrapped in a minimal ELF file.
+ struct Image {
+ spec: Vec<u8>,
+ tail: Vec<u8>,
+ }
+
+ impl Image {
+ fn new() -> Self {
+ Image {
+ spec: vec![0; SPEC_SIZE],
+ tail: Vec::new(),
+ }
+ }
+
+ fn u32(&mut self, at: usize, v: u32) {
+ self.spec[at..at + 4].copy_from_slice(&v.to_le_bytes());
+ }
+
+ fn u64(&mut self, at: usize, v: u64) {
+ self.spec[at..at + 8].copy_from_slice(&v.to_le_bytes());
+ }
+
+ fn tail_vaddr(&self) -> u64 {
+ BASE + self.tail.len() as u64
+ }
+
+ fn string(&mut self, at: usize, s: &str) {
+ let vaddr = self.tail_vaddr();
+ self.tail.extend_from_slice(s.as_bytes());
+ self.tail.push(0);
+ self.u64(at, vaddr);
+ }
+
+ fn s64s(&mut self, at: usize, vals: &[i64]) {
+ while self.tail.len() % 8 != 0 {
+ self.tail.push(0);
+ }
+ let vaddr = self.tail_vaddr();
+ for v in vals {
+ self.tail.extend_from_slice(&v.to_le_bytes());
+ }
+ self.u64(at, vaddr);
+ }
+
+ fn elf(&self) -> Vec<u8> {
+ let mut content = self.tail.clone();
+ content.extend_from_slice(&self.spec);
+
+ let mut img = vec![0u8; CONTENT_OFFSET];
+ img[..4].copy_from_slice(b"\x7fELF");
+ img[4] = 2; // ELFCLASS64
+ img[5] = 1; // ELFDATA2LSB
+ img[6] = 1; // EV_CURRENT
+ img[16..18].copy_from_slice(&2u16.to_le_bytes()); // ET_EXEC
+ img[18..20].copy_from_slice(&62u16.to_le_bytes()); // EM_X86_64
+ img[20..24].copy_from_slice(&1u32.to_le_bytes());
+ img[40..48].copy_from_slice(&64u64.to_le_bytes()); // e_shoff
+ img[52..54].copy_from_slice(&64u16.to_le_bytes()); // e_ehsize
+ img[58..60].copy_from_slice(&64u16.to_le_bytes()); // e_shentsize
+ img[60..62].copy_from_slice(&2u16.to_le_bytes()); // e_shnum
+ let sh = 64 + 64; // section 1 follows the null section header at 64
+ img[sh + 4..sh + 8].copy_from_slice(&1u32.to_le_bytes()); // SHT_PROGBITS
+ img[sh + 8..sh + 16].copy_from_slice(&2u64.to_le_bytes()); // SHF_ALLOC
+ img[sh + 16..sh + 24].copy_from_slice(&BASE.to_le_bytes());
+ img[sh + 24..sh + 32].copy_from_slice(&(CONTENT_OFFSET as u64).to_le_bytes());
+ img[sh + 32..sh + 40].copy_from_slice(&(content.len() as u64).to_le_bytes());
+ img[sh + 48..sh + 56].copy_from_slice(&8u64.to_le_bytes());
+ img.extend_from_slice(&content);
+ img
+ }
+
+ fn parse(&mut self) -> Result<ApiSpec> {
+ self.string(0, "kapi_fixture");
+ while self.tail.len() % 8 != 0 {
+ self.tail.push(0);
+ }
+ let img = self.elf();
+ parse_binary_to_api_spec(&img, CONTENT_OFFSET + self.tail.len(), Endian::Little, true)
+ }
+ }
+
+ #[test]
+ fn every_array_slot_is_consumed() {
+ let mut img = Image::new();
+ img.u32(PARAM_MAGIC, magic::PARAMS);
+ img.u32(PARAM_MAGIC + 4, 16);
+ img.u32(RETURN_MAGIC, magic::RETURN);
+ img.u32(ERROR_MAGIC, magic::ERRORS);
+ img.u32(ERROR_MAGIC + 4, 32);
+ img.u32(LOCK_MAGIC, magic::LOCKS);
+ img.u32(LOCK_MAGIC + 4, 16);
+ img.u32(CONSTRAINT_MAGIC, magic::CONSTRAINTS);
+ img.u32(CONSTRAINT_MAGIC + 4, 32);
+ img.u32(SIGNAL_MAGIC, magic::SIGNALS);
+ img.u32(SIGNAL_MAGIC + 4, 32);
+ img.u32(SIGMASK_MAGIC, magic::SIGMASK);
+ img.u32(SIGMASK_MAGIC + 4, 32);
+ img.u32(STRUCT_MAGIC, magic::STRUCTS);
+ img.u32(STRUCT_MAGIC + 4, 8);
+ img.u32(EFFECT_MAGIC, magic::EFFECTS);
+ img.u32(EFFECT_MAGIC + 4, 32);
+ img.u32(TRANS_MAGIC, magic::TRANS);
+ img.u32(TRANS_MAGIC + 4, 8);
+ img.u32(CAP_MAGIC, magic::CAPS);
+ img.u32(CAP_MAGIC + 4, 8);
+
+ img.string(PARAMS + 15 * PARAM_SIZE, "last_param");
+ img.u32(ERRORS + 31 * ERROR_SIZE, -7i32 as u32);
+ img.string(ERRORS + 31 * ERROR_SIZE + 8, "ELAST");
+ img.string(LOCKS + 15 * LOCK_SIZE, "last_lock");
+ img.string(CONSTRAINTS + 31 * CONSTRAINT_SIZE, "last_constraint");
+ img.u32(SIGNALS + 31 * SIGNAL_SIZE, 31);
+ img.u32(SIGNAL_MASKS + 31 * SIGNAL_MASK_SIZE + 8, 64);
+ img.u32(SIGNAL_MASKS + 31 * SIGNAL_MASK_SIZE + 136, 1);
+ img.string(SIGNAL_MASKS + 31 * SIGNAL_MASK_SIZE, "last mask");
+ img.string(SIGNAL_MASKS + 31 * SIGNAL_MASK_SIZE + 144, "mask desc");
+
+ let last_struct = STRUCT_SPECS + 7 * STRUCT_SPEC_SIZE;
+ img.string(last_struct, "last_struct");
+ img.u32(last_struct + 24, 16);
+ img.string(last_struct + 32 + 15 * STRUCT_FIELD_SIZE, "last_field");
+ img.string(last_struct + 32 + 15 * STRUCT_FIELD_SIZE + 80, "field desc");
+ img.string(last_struct + 1440, "struct desc");
+
+ img.string(SIDE_EFFECTS + 31 * SIDE_EFFECT_SIZE + 8, "last_effect");
+ img.string(
+ STATE_TRANSITIONS + 7 * STATE_TRANSITION_SIZE + 24,
+ "last_object",
+ );
+ let last_cap = CAPABILITIES + 7 * CAPABILITY_SIZE;
+ img.u32(last_cap, 40);
+ img.u32(last_cap + 52 + 7 * 4, 99);
+ img.u32(last_cap + 84, 8);
+
+ let spec = img.parse().unwrap();
+
+ assert_eq!(spec.parameters.len(), 16);
+ assert_eq!(spec.parameters[15].name, "last_param");
+ assert_eq!(spec.errors.len(), 32);
+ assert_eq!(spec.errors[31].error_code, -7);
+ assert_eq!(spec.errors[31].name, "ELAST");
+ assert_eq!(spec.locks[15].lock_name, "last_lock");
+ assert_eq!(spec.constraints[31].name, "last_constraint");
+ assert_eq!(spec.signals[31].signal_num, 31);
+ assert_eq!(spec.signal_masks.len(), 32);
+ assert_eq!(spec.signal_masks[31].name, "last mask");
+ assert_eq!(spec.signal_masks[31].signals, [64]);
+ assert_eq!(spec.signal_masks[31].description, "mask desc");
+
+ let st = &spec.struct_specs[7];
+ assert_eq!(st.name, "last_struct");
+ assert_eq!(st.description, "struct desc");
+ assert_eq!(st.field_count, 16);
+ assert_eq!(st.fields[15].name, "last_field");
+ assert_eq!(st.fields[15].description, "field desc");
+
+ assert_eq!(spec.side_effects[31].target, "last_effect");
+ assert_eq!(spec.state_transitions[7].object, "last_object");
+ let cap = &spec.capabilities[7];
+ assert_eq!(cap.capability, 40);
+ assert_eq!(cap.alternatives, [0, 0, 0, 0, 0, 0, 0, 99]);
+ }
+
+ #[test]
+ fn notes_and_signal_masks_are_read_without_their_markers() {
+ let mut img = Image::new();
+ img.u32(SIGMASK_MAGIC + 4, 2);
+ img.string(NOTES, "only notes");
+ img.string(SIGNAL_MASKS, "first");
+ img.u32(SIGNAL_MASKS + 8, 2);
+ img.u32(SIGNAL_MASKS + 12, 15);
+ img.u32(SIGNAL_MASKS + 136, 2);
+ img.string(SIGNAL_MASKS + 144, "first desc");
+ img.string(SIGNAL_MASKS + SIGNAL_MASK_SIZE, "second");
+
+ let spec = img.parse().unwrap();
+
+ assert_eq!(spec.examples, None);
+ assert_eq!(spec.notes.as_deref(), Some("only notes"));
+ assert_eq!(spec.signal_masks.len(), 2);
+ assert_eq!(spec.signal_masks[0].name, "first");
+ assert_eq!(spec.signal_masks[0].description, "first desc");
+ assert_eq!(spec.signal_masks[0].signals, [2, 15]);
+ assert_eq!(spec.signal_masks[1].name, "second");
+ assert!(spec.signal_masks[1].signals.is_empty());
+ }
+
+ #[test]
+ fn examples_are_read_next_to_notes() {
+ let mut img = Image::new();
+ img.u32(INFO_MAGIC, magic::INFO);
+ img.string(INFO_MAGIC + 8, "an example");
+ img.string(NOTES, "a note");
+
+ let spec = img.parse().unwrap();
+
+ assert_eq!(spec.examples.as_deref(), Some("an example"));
+ assert_eq!(spec.notes.as_deref(), Some("a note"));
+ }
+
+ #[test]
+ fn enum_and_error_values_are_followed_through_their_pointers() {
+ let mut img = Image::new();
+ img.u32(PARAM_MAGIC, magic::PARAMS);
+ img.u32(PARAM_MAGIC + 4, 2);
+ img.string(PARAMS, "mode");
+ img.s64s(PARAMS + 64, &[0, 1, -7, 1 << 40]);
+ img.u32(PARAMS + 72, 4);
+ img.string(PARAMS + PARAM_SIZE, "plain");
+ img.u32(RETURN_MAGIC, magic::RETURN);
+ img.string(RETURN_SPEC, "long");
+ img.u32(RETURN_SPEC + 12, 2);
+ img.s64s(RETURN_SPEC + 40, &[-22, -2, -(1 << 40)]);
+ img.u32(RETURN_SPEC + 48, 3);
+
+ let spec = img.parse().unwrap();
+
+ assert_eq!(
+ spec.parameters[0].enum_values,
+ ["0", "1", "-7", "1099511627776"]
+ );
+ assert!(spec.parameters[1].enum_values.is_empty());
+ let ret = spec.return_spec.unwrap();
+ assert_eq!(ret.check_type, 2);
+ assert_eq!(ret.error_values, [-22, -2]);
+ }
+
+ #[test]
+ fn numbers_the_constraint_does_not_use_are_unset() {
+ let mut img = Image::new();
+ img.u32(PARAM_MAGIC, magic::PARAMS);
+ img.u32(PARAM_MAGIC + 4, 4);
+ img.string(PARAMS, "plain");
+ let ranged = PARAMS + PARAM_SIZE;
+ img.string(ranged, "ranged");
+ img.u64(ranged + 24, 16);
+ img.u64(ranged + 40, -5i64 as u64);
+ img.u64(ranged + 48, 9);
+ img.u64(ranged + 56, 0xff);
+ img.u32(ranged + 76, 1);
+ let string = PARAMS + 2 * PARAM_SIZE;
+ img.string(string, "string");
+ img.u64(string + 40, 1);
+ img.u64(string + 48, 255);
+ img.u32(string + 76, 8);
+ let unlimited = PARAMS + 3 * PARAM_SIZE;
+ img.string(unlimited, "unlimited");
+ img.u32(unlimited + 76, 8);
+ img.u32(RETURN_MAGIC, magic::RETURN);
+ img.string(RETURN_SPEC, "long");
+ img.u32(RETURN_SPEC + 12, 1);
+ img.u64(RETURN_SPEC + 16, 7);
+ img.u64(RETURN_SPEC + 32, 100);
+
+ let spec = img.parse().unwrap();
+
+ let plain = &spec.parameters[0];
+ assert_eq!((plain.min_value, plain.max_value), (None, None));
+ assert_eq!(
+ (plain.valid_mask, plain.size, plain.alignment),
+ (None, None, None)
+ );
+ let ranged = &spec.parameters[1];
+ assert_eq!((ranged.min_value, ranged.max_value), (Some(-5), Some(9)));
+ assert_eq!((ranged.valid_mask, ranged.size), (None, Some(16)));
+ let string = &spec.parameters[2];
+ assert_eq!((string.min_value, string.max_value), (Some(1), Some(255)));
+ let unlimited = &spec.parameters[3];
+ assert_eq!((unlimited.min_value, unlimited.max_value), (None, None));
+ let ret = spec.return_spec.unwrap();
+ assert_eq!(ret.success_value, None);
+ assert_eq!((ret.success_min, ret.success_max), (Some(0), Some(100)));
+ }
+
+ #[test]
+ fn enum_values_behind_a_dangling_pointer_are_dropped() {
+ let mut img = Image::new();
+ img.u32(PARAM_MAGIC, magic::PARAMS);
+ img.u32(PARAM_MAGIC + 4, 1);
+ img.string(PARAMS, "mode");
+ img.u64(PARAMS + 64, 0x1000);
+ img.u32(PARAMS + 72, 4);
+
+ let spec = img.parse().unwrap();
+
+ assert!(spec.parameters[0].enum_values.is_empty());
+ }
+
+ #[test]
+ fn unexpected_section_marker_is_rejected() {
+ let mut img = Image::new();
+ img.u32(ERROR_MAGIC, 0xdead_beef);
+
+ let err = img.parse().unwrap_err();
+
+ assert!(err.to_string().contains("0xdeadbeef"), "{err}");
+ }
+
+ #[test]
+ fn truncated_spec_is_rejected() {
+ let mut img = Image::new();
+ img.spec.truncate(SIGNAL_MASKS);
+
+ let err = img.parse().unwrap_err();
+
+ assert!(err.to_string().contains("past the end"), "{err}");
+ }
+}
diff --git a/tools/kapi/src/formatter/json.rs b/tools/kapi/src/formatter/json.rs
new file mode 100644
index 0000000000000..5f2367ad12d40
--- /dev/null
+++ b/tools/kapi/src/formatter/json.rs
@@ -0,0 +1,659 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+use super::OutputFormatter;
+use crate::extractor::{
+ CapabilitySpec, ConstraintSpec, ErrorSpec, LockSpec, ParamSpec, ReturnSpec, SideEffectSpec,
+ SignalMaskSpec, SignalSpec, StateTransitionSpec, StructSpec,
+};
+use serde::Serialize;
+use std::io::Write;
+
+pub struct JsonFormatter {
+ data: JsonData,
+}
+
+#[derive(Serialize)]
+struct JsonData {
+ #[serde(skip_serializing_if = "Option::is_none")]
+ apis: Option<Vec<JsonApi>>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ api_details: Option<JsonApiDetails>,
+}
+
+#[derive(Serialize)]
+struct JsonApi {
+ name: String,
+ api_type: String,
+}
+
+#[derive(Serialize)]
+struct JsonApiDetails {
+ name: String,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ description: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ long_description: Option<String>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ context_flags: Vec<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ examples: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ notes: Option<String>,
+ // Sysfs-specific fields
+ #[serde(skip_serializing_if = "Option::is_none")]
+ subsystem: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ sysfs_path: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ permissions: Option<String>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ capabilities: Vec<CapabilitySpec>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ state_transitions: Vec<StateTransitionSpec>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ side_effects: Vec<SideEffectSpec>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ parameters: Vec<ParamSpec>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ return_spec: Option<ReturnSpec>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ errors: Vec<ErrorSpec>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ locks: Vec<LockSpec>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ struct_specs: Vec<StructSpec>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ signals: Vec<SignalSpec>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ signal_masks: Vec<SignalMaskSpec>,
+ #[serde(skip_serializing_if = "Vec::is_empty")]
+ constraints: Vec<ConstraintSpec>,
+}
+
+impl JsonFormatter {
+ pub fn new() -> Self {
+ JsonFormatter {
+ data: JsonData {
+ apis: None,
+ api_details: None,
+ },
+ }
+ }
+}
+
+impl OutputFormatter for JsonFormatter {
+ fn begin_document(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn end_document(&mut self, w: &mut dyn Write) -> std::io::Result<()> {
+ let json = serde_json::to_string_pretty(&self.data)?;
+ writeln!(w, "{json}")?;
+ Ok(())
+ }
+
+ fn begin_api_list(&mut self, _w: &mut dyn Write, _title: &str) -> std::io::Result<()> {
+ if self.data.apis.is_none() {
+ self.data.apis = Some(Vec::new());
+ }
+ Ok(())
+ }
+
+ fn api_item(&mut self, _w: &mut dyn Write, name: &str, api_type: &str) -> std::io::Result<()> {
+ if let Some(apis) = &mut self.data.apis {
+ apis.push(JsonApi {
+ name: name.to_string(),
+ api_type: api_type.to_string(),
+ });
+ }
+ Ok(())
+ }
+
+ fn end_api_list(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn total_specs(&mut self, _w: &mut dyn Write, _count: usize) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_api_details(&mut self, _w: &mut dyn Write, name: &str) -> std::io::Result<()> {
+ self.data.api_details = Some(JsonApiDetails {
+ name: name.to_string(),
+ description: None,
+ long_description: None,
+ context_flags: Vec::new(),
+ examples: None,
+ notes: None,
+ subsystem: None,
+ sysfs_path: None,
+ permissions: None,
+ capabilities: Vec::new(),
+ state_transitions: Vec::new(),
+ side_effects: Vec::new(),
+ parameters: Vec::new(),
+ return_spec: None,
+ errors: Vec::new(),
+ locks: Vec::new(),
+ struct_specs: Vec::new(),
+ signals: Vec::new(),
+ signal_masks: Vec::new(),
+ constraints: Vec::new(),
+ });
+ Ok(())
+ }
+
+ fn end_api_details(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn description(&mut self, _w: &mut dyn Write, desc: &str) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.description = Some(desc.to_string());
+ }
+ Ok(())
+ }
+
+ fn long_description(&mut self, _w: &mut dyn Write, desc: &str) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.long_description = Some(desc.to_string());
+ }
+ Ok(())
+ }
+
+ fn begin_context_flags(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn context_flag(&mut self, _w: &mut dyn Write, flag: &str) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.context_flags.push(flag.to_string());
+ }
+ Ok(())
+ }
+
+ fn end_context_flags(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_parameters(&mut self, _w: &mut dyn Write, _count: u32) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn end_parameters(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_errors(&mut self, _w: &mut dyn Write, _count: u32) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn end_errors(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn examples(&mut self, _w: &mut dyn Write, examples: &str) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.examples = Some(examples.to_string());
+ }
+ Ok(())
+ }
+
+ fn notes(&mut self, _w: &mut dyn Write, notes: &str) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.notes = Some(notes.to_string());
+ }
+ Ok(())
+ }
+
+ fn sysfs_subsystem(&mut self, _w: &mut dyn Write, subsystem: &str) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.subsystem = Some(subsystem.to_string());
+ }
+ Ok(())
+ }
+
+ fn sysfs_path(&mut self, _w: &mut dyn Write, path: &str) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.sysfs_path = Some(path.to_string());
+ }
+ Ok(())
+ }
+
+ fn sysfs_permissions(&mut self, _w: &mut dyn Write, perms: &str) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.permissions = Some(perms.to_string());
+ }
+ Ok(())
+ }
+
+ fn begin_capabilities(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn capability(&mut self, _w: &mut dyn Write, cap: &CapabilitySpec) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.capabilities.push(cap.clone());
+ }
+ Ok(())
+ }
+
+ fn end_capabilities(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn parameter(&mut self, _w: &mut dyn Write, param: &ParamSpec) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.parameters.push(param.clone());
+ }
+ Ok(())
+ }
+
+ fn return_spec(&mut self, _w: &mut dyn Write, ret: &ReturnSpec) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.return_spec = Some(ret.clone());
+ }
+ Ok(())
+ }
+
+ fn error(&mut self, _w: &mut dyn Write, error: &ErrorSpec) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.errors.push(error.clone());
+ }
+ Ok(())
+ }
+
+ fn begin_signals(&mut self, _w: &mut dyn Write, _count: u32) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn signal(&mut self, _w: &mut dyn Write, signal: &SignalSpec) -> std::io::Result<()> {
+ if let Some(api_details) = &mut self.data.api_details {
+ api_details.signals.push(signal.clone());
+ }
+ Ok(())
+ }
+
+ fn end_signals(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_signal_masks(&mut self, _w: &mut dyn Write, _count: u32) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn signal_mask(&mut self, _w: &mut dyn Write, mask: &SignalMaskSpec) -> std::io::Result<()> {
+ if let Some(api_details) = &mut self.data.api_details {
+ api_details.signal_masks.push(mask.clone());
+ }
+ Ok(())
+ }
+
+ fn end_signal_masks(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_side_effects(&mut self, _w: &mut dyn Write, _count: u32) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn side_effect(&mut self, _w: &mut dyn Write, effect: &SideEffectSpec) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.side_effects.push(effect.clone());
+ }
+ Ok(())
+ }
+
+ fn end_side_effects(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_state_transitions(&mut self, _w: &mut dyn Write, _count: u32) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn state_transition(
+ &mut self,
+ _w: &mut dyn Write,
+ trans: &StateTransitionSpec,
+ ) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.state_transitions.push(trans.clone());
+ }
+ Ok(())
+ }
+
+ fn end_state_transitions(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_constraints(&mut self, _w: &mut dyn Write, _count: u32) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn constraint(
+ &mut self,
+ _w: &mut dyn Write,
+ constraint: &ConstraintSpec,
+ ) -> std::io::Result<()> {
+ if let Some(api_details) = &mut self.data.api_details {
+ api_details.constraints.push(constraint.clone());
+ }
+ Ok(())
+ }
+
+ fn end_constraints(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_locks(&mut self, _w: &mut dyn Write, _count: u32) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn lock(&mut self, _w: &mut dyn Write, lock: &LockSpec) -> std::io::Result<()> {
+ if let Some(details) = &mut self.data.api_details {
+ details.locks.push(lock.clone());
+ }
+ Ok(())
+ }
+
+ fn end_locks(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_struct_specs(&mut self, _w: &mut dyn Write, _count: u32) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn struct_spec(&mut self, _w: &mut dyn Write, spec: &StructSpec) -> std::io::Result<()> {
+ if let Some(ref mut details) = self.data.api_details {
+ details.struct_specs.push(spec.clone());
+ }
+ Ok(())
+ }
+
+ fn end_struct_specs(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::extractor::{ErrorSpec, ParamSpec, ReturnSpec};
+
+ fn render_json(f: &mut JsonFormatter) -> String {
+ let mut buf = Vec::new();
+ f.end_document(&mut buf).unwrap();
+ String::from_utf8(buf).unwrap()
+ }
+
+ #[test]
+ fn json_output_is_valid() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.description(&mut sink, "A test syscall").unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+
+ // Verify it parses as valid JSON
+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+ assert_eq!(parsed["api_details"]["name"].as_str(), Some("sys_test"));
+ assert_eq!(
+ parsed["api_details"]["description"].as_str(),
+ Some("A test syscall")
+ );
+ }
+
+ #[test]
+ fn json_api_list() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_list(&mut sink, "Syscalls").unwrap();
+ f.api_item(&mut sink, "sys_open", "syscall").unwrap();
+ f.api_item(&mut sink, "sys_read", "syscall").unwrap();
+ f.end_api_list(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+
+ let apis = parsed["apis"].as_array().unwrap();
+ assert_eq!(apis.len(), 2);
+ assert_eq!(apis[0]["name"].as_str(), Some("sys_open"));
+ assert_eq!(apis[0]["api_type"].as_str(), Some("syscall"));
+ assert_eq!(apis[1]["name"].as_str(), Some("sys_read"));
+ }
+
+ #[test]
+ fn json_special_characters_in_description() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.description(&mut sink, "Contains \"quotes\" and \\backslashes\\")
+ .unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+
+ // Must be valid JSON despite special characters
+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+ assert_eq!(
+ parsed["api_details"]["description"].as_str(),
+ Some("Contains \"quotes\" and \\backslashes\\")
+ );
+ }
+
+ #[test]
+ fn json_special_characters_in_name() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_list(&mut sink, "APIs").unwrap();
+ // Names with underscores (common in kernel) and unusual strings
+ f.api_item(&mut sink, "sys_new\tline", "syscall").unwrap();
+ f.end_api_list(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+
+ // Must parse correctly; serde_json handles escaping for us
+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+ assert_eq!(parsed["apis"][0]["name"].as_str(), Some("sys_new\tline"));
+ }
+
+ #[test]
+ fn json_parameters_serialized() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_write").unwrap();
+ f.begin_parameters(&mut sink, 2).unwrap();
+ f.parameter(
+ &mut sink,
+ &ParamSpec {
+ index: 0,
+ name: "fd".to_string(),
+ type_name: "unsigned int".to_string(),
+ description: "file descriptor".to_string(),
+ flags: 1,
+ param_type: 2,
+ constraint_type: 0,
+ constraint: None,
+ min_value: Some(0),
+ max_value: Some(1024),
+ valid_mask: None,
+ enum_values: vec![],
+ size: None,
+ alignment: None,
+ size_param_idx: None,
+ },
+ )
+ .unwrap();
+ f.end_parameters(&mut sink).unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+
+ let params = parsed["api_details"]["parameters"].as_array().unwrap();
+ assert_eq!(params.len(), 1);
+ assert_eq!(params[0]["name"].as_str(), Some("fd"));
+ assert_eq!(params[0]["param_type"].as_u64(), Some(2));
+ }
+
+ #[test]
+ fn json_errors_serialized() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_read").unwrap();
+ f.begin_errors(&mut sink, 1).unwrap();
+ f.error(
+ &mut sink,
+ &ErrorSpec {
+ error_code: -9,
+ name: "EBADF".to_string(),
+ condition: "fd is not valid".to_string(),
+ description: "Bad file descriptor".to_string(),
+ },
+ )
+ .unwrap();
+ f.end_errors(&mut sink).unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+
+ let errors = parsed["api_details"]["errors"].as_array().unwrap();
+ assert_eq!(errors.len(), 1);
+ assert_eq!(errors[0]["name"].as_str(), Some("EBADF"));
+ assert_eq!(errors[0]["error_code"].as_i64(), Some(-9));
+ }
+
+ #[test]
+ fn json_empty_details_omits_empty_fields() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_empty").unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+
+ // description should not be present (skip_serializing_if = Option::is_none)
+ assert!(parsed["api_details"]["description"].is_null());
+ // parameters empty array should not be present (skip_serializing_if = Vec::is_empty)
+ assert!(parsed["api_details"]["parameters"].is_null());
+ // errors empty array should not be present
+ assert!(parsed["api_details"]["errors"].is_null());
+ }
+
+ #[test]
+ fn json_braces_balance() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_balanced").unwrap();
+ f.description(&mut sink, "Test braces balance").unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+
+ let open_braces = json.chars().filter(|&c| c == '{').count();
+ let close_braces = json.chars().filter(|&c| c == '}').count();
+ assert_eq!(open_braces, close_braces, "Braces are unbalanced");
+
+ let open_brackets = json.chars().filter(|&c| c == '[').count();
+ let close_brackets = json.chars().filter(|&c| c == ']').count();
+ assert_eq!(open_brackets, close_brackets, "Brackets are unbalanced");
+ }
+
+ #[test]
+ fn json_return_spec_serialized() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_open").unwrap();
+ f.return_spec(
+ &mut sink,
+ &ReturnSpec {
+ type_name: "int".to_string(),
+ description: "file descriptor on success".to_string(),
+ return_type: 1,
+ check_type: 3,
+ success_value: Some(0),
+ success_min: None,
+ success_max: None,
+ error_values: vec![-1],
+ },
+ )
+ .unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+
+ let ret = &parsed["api_details"]["return_spec"];
+ assert_eq!(ret["type_name"].as_str(), Some("int"));
+ assert_eq!(ret["check_type"].as_u64(), Some(3));
+ }
+
+ #[test]
+ fn json_unicode_in_description() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_uni").unwrap();
+ f.description(&mut sink, "Supports unicode: \u{00e9}\u{00e8}\u{00ea}")
+ .unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+ assert!(parsed["api_details"]["description"]
+ .as_str()
+ .unwrap()
+ .contains('\u{00e9}'));
+ }
+
+ #[test]
+ fn json_escapes_embedded_newlines() {
+ let mut f = JsonFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.long_description(&mut sink, "One.\n\n- a\n- b").unwrap();
+ f.examples(&mut sink, "a();\nb();").unwrap();
+ f.notes(&mut sink, "Note one.\n\nNote two.").unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let json = render_json(&mut f);
+ assert!(json.contains(r#""examples": "a();\nb();""#));
+ let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
+ assert_eq!(
+ parsed["api_details"]["long_description"].as_str(),
+ Some("One.\n\n- a\n- b")
+ );
+ assert_eq!(
+ parsed["api_details"]["notes"].as_str(),
+ Some("Note one.\n\nNote two.")
+ );
+ }
+}
diff --git a/tools/kapi/src/formatter/mod.rs b/tools/kapi/src/formatter/mod.rs
new file mode 100644
index 0000000000000..8d375cb310b0b
--- /dev/null
+++ b/tools/kapi/src/formatter/mod.rs
@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+use crate::extractor::{
+ CapabilitySpec, ConstraintSpec, ErrorSpec, LockSpec, ParamSpec, ReturnSpec, SideEffectSpec,
+ SignalMaskSpec, SignalSpec, StateTransitionSpec, StructSpec,
+};
+use std::io::Write;
+
+mod json;
+mod plain;
+mod rst;
+
+pub use json::JsonFormatter;
+pub use plain::PlainFormatter;
+pub use rst::RstFormatter;
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum OutputFormat {
+ Plain,
+ Json,
+ Rst,
+}
+
+impl std::str::FromStr for OutputFormat {
+ type Err = String;
+
+ fn from_str(s: &str) -> Result<Self, Self::Err> {
+ match s.to_lowercase().as_str() {
+ "plain" => Ok(OutputFormat::Plain),
+ "json" => Ok(OutputFormat::Json),
+ "rst" => Ok(OutputFormat::Rst),
+ _ => Err(format!("Unknown output format: {}", s)),
+ }
+ }
+}
+
+/// Names of the KAPI_PARAM_* flags set in `flags`.
+fn param_flag_names(flags: u32) -> Vec<&'static str> {
+ const IN: u32 = 1 << 0;
+ const OUT: u32 = 1 << 1;
+ const OTHER: [(u32, &str); 6] = [
+ (1 << 3, "OPTIONAL"),
+ (1 << 4, "CONST"),
+ (1 << 5, "VOLATILE"),
+ (1 << 6, "USER"),
+ (1 << 7, "DMA"),
+ (1 << 8, "ALIGNED"),
+ ];
+
+ let mut names = Vec::new();
+ if flags & (IN | OUT) == IN | OUT {
+ names.push("INOUT");
+ } else if flags & IN != 0 {
+ names.push("IN");
+ } else if flags & OUT != 0 {
+ names.push("OUT");
+ }
+ names.extend(
+ OTHER
+ .iter()
+ .filter(|(bit, _)| flags & bit != 0)
+ .map(|(_, name)| *name),
+ );
+ names
+}
+
+/// Text for a parameter's bounds; either end may be unset.
+fn range_text(min: Option<i64>, max: Option<i64>) -> Option<String> {
+ match (min, max) {
+ (Some(min), Some(max)) => Some(format!("{min} to {max}")),
+ (Some(min), None) => Some(format!(">= {min}")),
+ (None, Some(max)) => Some(format!("<= {max}")),
+ (None, None) => None,
+ }
+}
+
+/// Write `text` line by line, indenting every non-blank line by `indent`.
+fn write_indented(w: &mut dyn Write, indent: &str, text: &str) -> std::io::Result<()> {
+ for line in text.lines() {
+ if line.is_empty() {
+ writeln!(w)?;
+ } else {
+ writeln!(w, "{indent}{line}")?;
+ }
+ }
+ Ok(())
+}
+
+/// Prepare text with embedded newlines for reStructuredText. Wrapped
+/// prose stays in its paragraph, but a bullet list needs a blank line
+/// before its first item and after its last one to be recognised.
+fn rst_text(text: &str) -> String {
+ let mut out: Vec<&str> = Vec::new();
+ let mut prev_bullet = false;
+ for line in text.lines() {
+ let bullet = line.starts_with("- ");
+ if !line.is_empty() && bullet != prev_bullet && out.last().is_some_and(|l| !l.is_empty()) {
+ out.push("");
+ }
+ out.push(line);
+ if !line.is_empty() {
+ prev_bullet = bullet;
+ }
+ }
+ out.join("\n")
+}
+
+pub trait OutputFormatter {
+ fn begin_document(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+ fn end_document(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ fn begin_api_list(&mut self, w: &mut dyn Write, title: &str) -> std::io::Result<()>;
+ fn api_item(&mut self, w: &mut dyn Write, name: &str, api_type: &str) -> std::io::Result<()>;
+ fn end_api_list(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ fn total_specs(&mut self, w: &mut dyn Write, count: usize) -> std::io::Result<()>;
+
+ fn begin_api_details(&mut self, w: &mut dyn Write, name: &str) -> std::io::Result<()>;
+ fn end_api_details(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+ fn description(&mut self, w: &mut dyn Write, desc: &str) -> std::io::Result<()>;
+ fn long_description(&mut self, w: &mut dyn Write, desc: &str) -> std::io::Result<()>;
+
+ fn begin_context_flags(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+ fn context_flag(&mut self, w: &mut dyn Write, flag: &str) -> std::io::Result<()>;
+ fn end_context_flags(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ fn begin_parameters(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()>;
+ fn parameter(&mut self, w: &mut dyn Write, param: &ParamSpec) -> std::io::Result<()>;
+ fn end_parameters(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ fn return_spec(&mut self, w: &mut dyn Write, ret: &ReturnSpec) -> std::io::Result<()>;
+
+ fn begin_errors(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()>;
+ fn error(&mut self, w: &mut dyn Write, error: &ErrorSpec) -> std::io::Result<()>;
+ fn end_errors(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ fn examples(&mut self, w: &mut dyn Write, examples: &str) -> std::io::Result<()>;
+ fn notes(&mut self, w: &mut dyn Write, notes: &str) -> std::io::Result<()>;
+
+ // Sysfs-specific methods
+ fn sysfs_subsystem(&mut self, w: &mut dyn Write, subsystem: &str) -> std::io::Result<()>;
+ fn sysfs_path(&mut self, w: &mut dyn Write, path: &str) -> std::io::Result<()>;
+ fn sysfs_permissions(&mut self, w: &mut dyn Write, perms: &str) -> std::io::Result<()>;
+
+ fn begin_capabilities(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+ fn capability(&mut self, w: &mut dyn Write, cap: &CapabilitySpec) -> std::io::Result<()>;
+ fn end_capabilities(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ // Signal-related methods
+ fn begin_signals(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()>;
+ fn signal(&mut self, w: &mut dyn Write, signal: &SignalSpec) -> std::io::Result<()>;
+ fn end_signals(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ fn begin_signal_masks(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()>;
+ fn signal_mask(&mut self, w: &mut dyn Write, mask: &SignalMaskSpec) -> std::io::Result<()>;
+ fn end_signal_masks(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ // Side effects and state transitions
+ fn begin_side_effects(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()>;
+ fn side_effect(&mut self, w: &mut dyn Write, effect: &SideEffectSpec) -> std::io::Result<()>;
+ fn end_side_effects(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ fn begin_state_transitions(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()>;
+ fn state_transition(
+ &mut self,
+ w: &mut dyn Write,
+ trans: &StateTransitionSpec,
+ ) -> std::io::Result<()>;
+ fn end_state_transitions(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ // Constraints and locks
+ fn begin_constraints(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()>;
+ fn constraint(&mut self, w: &mut dyn Write, constraint: &ConstraintSpec)
+ -> std::io::Result<()>;
+ fn end_constraints(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ fn begin_locks(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()>;
+ fn lock(&mut self, w: &mut dyn Write, lock: &LockSpec) -> std::io::Result<()>;
+ fn end_locks(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+
+ fn begin_struct_specs(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()>;
+ fn struct_spec(&mut self, w: &mut dyn Write, spec: &StructSpec) -> std::io::Result<()>;
+ fn end_struct_specs(&mut self, w: &mut dyn Write) -> std::io::Result<()>;
+}
+
+pub fn create_formatter(format: OutputFormat) -> Box<dyn OutputFormatter> {
+ match format {
+ OutputFormat::Plain => Box::new(PlainFormatter::new()),
+ OutputFormat::Json => Box::new(JsonFormatter::new()),
+ OutputFormat::Rst => Box::new(RstFormatter::new()),
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn param_flags_use_the_header_bit_values() {
+ assert!(param_flag_names(0).is_empty());
+ assert_eq!(param_flag_names(0x1), ["IN"]);
+ assert_eq!(param_flag_names(0x2), ["OUT"]);
+ assert_eq!(param_flag_names(0x3), ["INOUT"]);
+ assert_eq!(param_flag_names(0x42), ["OUT", "USER"]);
+ assert_eq!(param_flag_names(0x9), ["IN", "OPTIONAL"]);
+ assert_eq!(
+ param_flag_names(0x1f8),
+ ["OPTIONAL", "CONST", "VOLATILE", "USER", "DMA", "ALIGNED"]
+ );
+ }
+
+ #[test]
+ fn range_text_shows_one_sided_bounds() {
+ assert_eq!(range_text(Some(0), Some(9)).as_deref(), Some("0 to 9"));
+ assert_eq!(range_text(Some(1), None).as_deref(), Some(">= 1"));
+ assert_eq!(range_text(None, Some(255)).as_deref(), Some("<= 255"));
+ assert_eq!(range_text(None, None), None);
+ }
+}
diff --git a/tools/kapi/src/formatter/plain.rs b/tools/kapi/src/formatter/plain.rs
new file mode 100644
index 0000000000000..0aa03ab8573b6
--- /dev/null
+++ b/tools/kapi/src/formatter/plain.rs
@@ -0,0 +1,679 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+use super::OutputFormatter;
+use crate::extractor::{
+ CapabilitySpec, ConstraintSpec, ErrorSpec, LockSpec, ParamSpec, ReturnSpec, SideEffectSpec,
+ SignalMaskSpec, SignalSpec, StateTransitionSpec,
+};
+use std::io::Write;
+
+pub struct PlainFormatter;
+
+impl PlainFormatter {
+ pub fn new() -> Self {
+ PlainFormatter
+ }
+}
+
+impl OutputFormatter for PlainFormatter {
+ fn begin_document(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn end_document(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_api_list(&mut self, w: &mut dyn Write, title: &str) -> std::io::Result<()> {
+ writeln!(w, "\n{title}:")?;
+ writeln!(w, "{}", "-".repeat(title.len() + 1))
+ }
+
+ fn api_item(&mut self, w: &mut dyn Write, name: &str, _api_type: &str) -> std::io::Result<()> {
+ writeln!(w, " {name}")
+ }
+
+ fn end_api_list(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn total_specs(&mut self, w: &mut dyn Write, count: usize) -> std::io::Result<()> {
+ writeln!(w, "\nTotal specifications found: {count}")
+ }
+
+ fn begin_api_details(&mut self, w: &mut dyn Write, name: &str) -> std::io::Result<()> {
+ writeln!(w, "\nDetailed information for {name}:")?;
+ writeln!(w, "{}=", "=".repeat(25 + name.len()))
+ }
+
+ fn end_api_details(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn description(&mut self, w: &mut dyn Write, desc: &str) -> std::io::Result<()> {
+ writeln!(w, "Description: {desc}")
+ }
+
+ fn long_description(&mut self, w: &mut dyn Write, desc: &str) -> std::io::Result<()> {
+ writeln!(w, "\nDetailed Description:")?;
+ super::write_indented(w, " ", desc)
+ }
+
+ fn begin_context_flags(&mut self, w: &mut dyn Write) -> std::io::Result<()> {
+ writeln!(w, "\nExecution Context:")
+ }
+
+ fn context_flag(&mut self, w: &mut dyn Write, flag: &str) -> std::io::Result<()> {
+ writeln!(w, " - {flag}")
+ }
+
+ fn end_context_flags(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_parameters(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ writeln!(w, "\nParameters ({count}):")
+ }
+
+ fn parameter(&mut self, w: &mut dyn Write, param: &ParamSpec) -> std::io::Result<()> {
+ writeln!(
+ w,
+ " [{}] {} ({})",
+ param.index, param.name, param.type_name
+ )?;
+ if !param.description.is_empty() {
+ writeln!(w, " {}", param.description)?;
+ }
+
+ // Display flags
+ let flags = super::param_flag_names(param.flags);
+ if !flags.is_empty() {
+ writeln!(w, " Flags: {}", flags.join(" | "))?;
+ }
+
+ // Display constraints
+ if let Some(constraint) = ¶m.constraint {
+ writeln!(w, " Constraint: {constraint}")?;
+ }
+ if let Some(range) = super::range_text(param.min_value, param.max_value) {
+ writeln!(w, " Range: {range}")?;
+ }
+ if let Some(mask) = param.valid_mask {
+ writeln!(w, " Valid mask: 0x{mask:x}")?;
+ }
+ Ok(())
+ }
+
+ fn end_parameters(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn return_spec(&mut self, w: &mut dyn Write, ret: &ReturnSpec) -> std::io::Result<()> {
+ writeln!(w, "\nReturn Value:")?;
+ writeln!(w, " Type: {}", ret.type_name)?;
+ writeln!(w, " {}", ret.description)?;
+ if let Some(val) = ret.success_value {
+ writeln!(w, " Success value: {val}")?;
+ }
+ if let (Some(min), Some(max)) = (ret.success_min, ret.success_max) {
+ writeln!(w, " Success range: {min} to {max}")?;
+ }
+ Ok(())
+ }
+
+ fn begin_errors(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ writeln!(w, "\nPossible Errors ({count}):")
+ }
+
+ fn error(&mut self, w: &mut dyn Write, error: &ErrorSpec) -> std::io::Result<()> {
+ writeln!(w, " {} ({})", error.name, error.error_code)?;
+ if !error.condition.is_empty() {
+ writeln!(w, " Condition: {}", error.condition)?;
+ }
+ if !error.description.is_empty() {
+ writeln!(w, " {}", error.description)?;
+ }
+ Ok(())
+ }
+
+ fn end_errors(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn examples(&mut self, w: &mut dyn Write, examples: &str) -> std::io::Result<()> {
+ writeln!(w, "\nExamples:")?;
+ super::write_indented(w, " ", examples)
+ }
+
+ fn notes(&mut self, w: &mut dyn Write, notes: &str) -> std::io::Result<()> {
+ writeln!(w, "\nNotes:")?;
+ super::write_indented(w, " ", notes)
+ }
+
+ fn sysfs_subsystem(&mut self, w: &mut dyn Write, subsystem: &str) -> std::io::Result<()> {
+ writeln!(w, "Subsystem: {subsystem}")
+ }
+
+ fn sysfs_path(&mut self, w: &mut dyn Write, path: &str) -> std::io::Result<()> {
+ writeln!(w, "Sysfs Path: {path}")
+ }
+
+ fn sysfs_permissions(&mut self, w: &mut dyn Write, perms: &str) -> std::io::Result<()> {
+ writeln!(w, "Permissions: {perms}")
+ }
+
+ fn begin_capabilities(&mut self, w: &mut dyn Write) -> std::io::Result<()> {
+ writeln!(w, "\nRequired Capabilities:")
+ }
+
+ fn capability(&mut self, w: &mut dyn Write, cap: &CapabilitySpec) -> std::io::Result<()> {
+ writeln!(w, " {} ({}) - {}", cap.name, cap.capability, cap.action)?;
+ if !cap.allows.is_empty() {
+ writeln!(w, " Allows: {}", cap.allows)?;
+ }
+ if !cap.without_cap.is_empty() {
+ writeln!(w, " Without capability: {}", cap.without_cap)?;
+ }
+ if let Some(cond) = &cap.check_condition {
+ writeln!(w, " Condition: {cond}")?;
+ }
+ Ok(())
+ }
+
+ fn end_capabilities(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ // Signal-related methods
+ fn begin_signals(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ writeln!(w, "\nSignal Specifications ({count}):")
+ }
+
+ fn signal(&mut self, w: &mut dyn Write, signal: &SignalSpec) -> std::io::Result<()> {
+ write!(w, " {} ({})", signal.signal_name, signal.signal_num)?;
+
+ // Display direction (bitmask matching C enum kapi_signal_direction)
+ let mut dirs = Vec::new();
+ if signal.direction & 1 != 0 {
+ dirs.push("RECEIVE");
+ }
+ if signal.direction & 2 != 0 {
+ dirs.push("SEND");
+ }
+ if signal.direction & 4 != 0 {
+ dirs.push("HANDLE");
+ }
+ if signal.direction & 8 != 0 {
+ dirs.push("BLOCK");
+ }
+ if signal.direction & 16 != 0 {
+ dirs.push("IGNORE");
+ }
+ let direction = if dirs.is_empty() {
+ "UNKNOWN".to_string()
+ } else {
+ dirs.join("|")
+ };
+ write!(w, " - {direction}")?;
+
+ // Display action (matching C enum kapi_signal_action)
+ let action = match signal.action {
+ 0 => "DEFAULT",
+ 1 => "TERMINATE",
+ 2 => "COREDUMP",
+ 3 => "STOP",
+ 4 => "CONTINUE",
+ 5 => "CUSTOM",
+ 6 => "RETURN",
+ 7 => "RESTART",
+ 8 => "QUEUE",
+ 9 => "DISCARD",
+ 10 => "TRANSFORM",
+ _ => "UNKNOWN",
+ };
+ writeln!(w, " - {action}")?;
+
+ if let Some(target) = &signal.target {
+ writeln!(w, " Target: {target}")?;
+ }
+ if let Some(condition) = &signal.condition {
+ writeln!(w, " Condition: {condition}")?;
+ }
+ if let Some(desc) = &signal.description {
+ writeln!(w, " {desc}")?;
+ }
+
+ // Display timing
+ let timing = match signal.timing {
+ 0 => "BEFORE",
+ 1 => "DURING",
+ 2 => "AFTER",
+ 3 => "EXIT",
+ _ => "UNKNOWN",
+ };
+ writeln!(w, " Timing: {timing}")?;
+ writeln!(w, " Priority: {}", signal.priority)?;
+
+ if signal.restartable {
+ writeln!(w, " Restartable: yes")?;
+ }
+ if signal.interruptible {
+ writeln!(w, " Interruptible: yes")?;
+ }
+ if let Some(queue) = &signal.queue {
+ writeln!(w, " Queue: {queue}")?;
+ }
+ if signal.sa_flags_required != 0 {
+ writeln!(
+ w,
+ " SA flags required: {:#x}",
+ signal.sa_flags_required
+ )?;
+ }
+ if signal.sa_flags_forbidden != 0 {
+ writeln!(
+ w,
+ " SA flags forbidden: {:#x}",
+ signal.sa_flags_forbidden
+ )?;
+ }
+ if signal.state_required != 0 {
+ writeln!(w, " State required: {:#x}", signal.state_required)?;
+ }
+ if signal.state_forbidden != 0 {
+ writeln!(w, " State forbidden: {:#x}", signal.state_forbidden)?;
+ }
+ if let Some(error) = signal.error_on_signal {
+ writeln!(w, " Error on signal: {error}")?;
+ }
+ if let Some(transform) = signal.transform_to {
+ writeln!(w, " Transform to: {transform}")?;
+ }
+ Ok(())
+ }
+
+ fn end_signals(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_signal_masks(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ writeln!(w, "\nSignal Masks ({count}):")
+ }
+
+ fn signal_mask(&mut self, w: &mut dyn Write, mask: &SignalMaskSpec) -> std::io::Result<()> {
+ writeln!(w, " {}", mask.name)?;
+ if !mask.description.is_empty() {
+ writeln!(w, " {}", mask.description)?;
+ }
+ if !mask.signals.is_empty() {
+ let signals: Vec<String> = mask.signals.iter().map(i32::to_string).collect();
+ writeln!(w, " Signals: {}", signals.join(", "))?;
+ }
+ Ok(())
+ }
+
+ fn end_signal_masks(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ // Side effects and state transitions
+ fn begin_side_effects(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ writeln!(w, "\nSide Effects ({count}):")
+ }
+
+ fn side_effect(&mut self, w: &mut dyn Write, effect: &SideEffectSpec) -> std::io::Result<()> {
+ writeln!(w, " {} - {}", effect.target, effect.description)?;
+ if let Some(condition) = &effect.condition {
+ writeln!(w, " Condition: {condition}")?;
+ }
+ if effect.reversible {
+ writeln!(w, " Reversible: yes")?;
+ }
+ Ok(())
+ }
+
+ fn end_side_effects(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_state_transitions(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ writeln!(w, "\nState Transitions ({count}):")
+ }
+
+ fn state_transition(
+ &mut self,
+ w: &mut dyn Write,
+ trans: &StateTransitionSpec,
+ ) -> std::io::Result<()> {
+ writeln!(
+ w,
+ " {} : {} -> {}",
+ trans.object, trans.from_state, trans.to_state
+ )?;
+ if let Some(condition) = &trans.condition {
+ writeln!(w, " Condition: {condition}")?;
+ }
+ if !trans.description.is_empty() {
+ writeln!(w, " {}", trans.description)?;
+ }
+ Ok(())
+ }
+
+ fn end_state_transitions(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ // Constraints and locks
+ fn begin_constraints(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ writeln!(w, "\nAdditional Constraints ({count}):")
+ }
+
+ fn constraint(
+ &mut self,
+ w: &mut dyn Write,
+ constraint: &ConstraintSpec,
+ ) -> std::io::Result<()> {
+ writeln!(w, " {}", constraint.name)?;
+ if !constraint.description.is_empty() {
+ writeln!(w, " {}", constraint.description)?;
+ }
+ if let Some(expr) = &constraint.expression {
+ writeln!(w, " Expression: {expr}")?;
+ }
+ Ok(())
+ }
+
+ fn end_constraints(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_locks(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ writeln!(w, "\nLocking Requirements ({count}):")
+ }
+
+ fn lock(&mut self, w: &mut dyn Write, lock: &LockSpec) -> std::io::Result<()> {
+ write!(w, " {}", lock.lock_name)?;
+
+ // Display lock type
+ let lock_type = match lock.lock_type {
+ 0 => "NONE",
+ 1 => "MUTEX",
+ 2 => "SPINLOCK",
+ 3 => "RWLOCK",
+ 4 => "SEQLOCK",
+ 5 => "RCU",
+ 6 => "SEMAPHORE",
+ 7 => "CUSTOM",
+ _ => "UNKNOWN",
+ };
+ writeln!(w, " ({lock_type})")?;
+
+ let scope_str = match lock.scope {
+ 0 => "acquired and released",
+ 1 => "acquired (not released)",
+ 2 => "released (held on entry)",
+ 3 => "held by caller",
+ _ => "unknown",
+ };
+ writeln!(w, " Scope: {scope_str}")?;
+
+ if !lock.description.is_empty() {
+ writeln!(w, " {}", lock.description)?;
+ }
+ Ok(())
+ }
+
+ fn end_locks(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_struct_specs(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ writeln!(w, "\nStructure Specifications ({count}):")
+ }
+
+ fn struct_spec(
+ &mut self,
+ w: &mut dyn Write,
+ spec: &crate::extractor::StructSpec,
+ ) -> std::io::Result<()> {
+ writeln!(
+ w,
+ " {} (size={}, align={}):",
+ spec.name, spec.size, spec.alignment
+ )?;
+ if !spec.description.is_empty() {
+ writeln!(w, " {}", spec.description)?;
+ }
+
+ if !spec.fields.is_empty() {
+ writeln!(w, " Fields ({}):", spec.field_count)?;
+ for field in &spec.fields {
+ write!(w, " - {} ({}):", field.name, field.type_name)?;
+ if !field.description.is_empty() {
+ write!(w, " {}", field.description)?;
+ }
+ writeln!(w)?;
+
+ // Show constraints if present
+ if field.min_value != 0 || field.max_value != 0 {
+ writeln!(
+ w,
+ " Range: [{}, {}]",
+ field.min_value, field.max_value
+ )?;
+ }
+ if field.valid_mask != 0 {
+ writeln!(w, " Mask: {:#x}", field.valid_mask)?;
+ }
+ }
+ }
+ Ok(())
+ }
+
+ fn end_struct_specs(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::extractor::{ErrorSpec, ParamSpec, ReturnSpec};
+
+ fn render_plain(f: &mut PlainFormatter, sink: &mut Vec<u8>) -> String {
+ f.end_document(sink).unwrap();
+ String::from_utf8(sink.clone()).unwrap()
+ }
+
+ #[test]
+ fn plain_api_list() {
+ let mut f = PlainFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_list(&mut sink, "System Calls").unwrap();
+ f.api_item(&mut sink, "sys_open", "syscall").unwrap();
+ f.api_item(&mut sink, "sys_read", "syscall").unwrap();
+ f.end_api_list(&mut sink).unwrap();
+ f.total_specs(&mut sink, 2).unwrap();
+
+ let out = render_plain(&mut f, &mut sink);
+ assert!(out.contains("sys_open"));
+ assert!(out.contains("sys_read"));
+ assert!(out.contains("Total specifications found: 2"));
+ }
+
+ #[test]
+ fn plain_api_details() {
+ let mut f = PlainFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.description(&mut sink, "A test syscall").unwrap();
+ f.long_description(&mut sink, "Detailed description here")
+ .unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_plain(&mut f, &mut sink);
+ assert!(out.contains("sys_test"));
+ assert!(out.contains("A test syscall"));
+ assert!(out.contains("Detailed description here"));
+ }
+
+ #[test]
+ fn plain_parameters() {
+ let mut f = PlainFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_write").unwrap();
+ f.begin_parameters(&mut sink, 1).unwrap();
+ f.parameter(
+ &mut sink,
+ &ParamSpec {
+ index: 0,
+ name: "fd".to_string(),
+ type_name: "unsigned int".to_string(),
+ description: "file descriptor".to_string(),
+ flags: 1,
+ param_type: 2,
+ constraint_type: 0,
+ constraint: None,
+ min_value: None,
+ max_value: None,
+ valid_mask: None,
+ enum_values: vec![],
+ size: None,
+ alignment: None,
+ size_param_idx: None,
+ },
+ )
+ .unwrap();
+ f.end_parameters(&mut sink).unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_plain(&mut f, &mut sink);
+ assert!(out.contains("fd"));
+ assert!(out.contains("unsigned int"));
+ assert!(out.contains("file descriptor"));
+ }
+
+ #[test]
+ fn plain_errors() {
+ let mut f = PlainFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.begin_errors(&mut sink, 1).unwrap();
+ f.error(
+ &mut sink,
+ &ErrorSpec {
+ error_code: -2,
+ name: "ENOENT".to_string(),
+ condition: "File not found".to_string(),
+ description: "The file does not exist".to_string(),
+ },
+ )
+ .unwrap();
+ f.end_errors(&mut sink).unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_plain(&mut f, &mut sink);
+ assert!(out.contains("ENOENT"));
+ assert!(out.contains("-2"));
+ assert!(out.contains("File not found"));
+ }
+
+ #[test]
+ fn plain_return_spec() {
+ let mut f = PlainFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.return_spec(
+ &mut sink,
+ &ReturnSpec {
+ type_name: "KAPI_TYPE_INT".to_string(),
+ description: "Returns 0 on success".to_string(),
+ return_type: 1,
+ check_type: 0,
+ success_value: Some(0),
+ success_min: None,
+ success_max: None,
+ error_values: vec![],
+ },
+ )
+ .unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_plain(&mut f, &mut sink);
+ assert!(out.contains("KAPI_TYPE_INT"));
+ assert!(out.contains("Returns 0 on success"));
+ }
+
+ #[test]
+ fn plain_context_flags() {
+ let mut f = PlainFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.begin_context_flags(&mut sink).unwrap();
+ f.context_flag(&mut sink, "KAPI_CTX_PROCESS").unwrap();
+ f.context_flag(&mut sink, "KAPI_CTX_SLEEPABLE").unwrap();
+ f.end_context_flags(&mut sink).unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_plain(&mut f, &mut sink);
+ assert!(out.contains("KAPI_CTX_PROCESS"));
+ assert!(out.contains("KAPI_CTX_SLEEPABLE"));
+ }
+
+ #[test]
+ fn plain_signal_mask_lists_its_signals() {
+ let mut f = PlainFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.begin_signal_masks(&mut sink, 1).unwrap();
+ f.signal_mask(
+ &mut sink,
+ &SignalMaskSpec {
+ name: "blocked".to_string(),
+ description: "Blocked while running".to_string(),
+ signals: vec![2, 15],
+ },
+ )
+ .unwrap();
+ f.end_signal_masks(&mut sink).unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_plain(&mut f, &mut sink);
+ assert!(out.contains(" blocked\n Blocked while running\n Signals: 2, 15\n"));
+ }
+
+ #[test]
+ fn plain_multiline_blocks_are_indented() {
+ let mut f = PlainFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.long_description(&mut sink, "First paragraph.\n\n- item one\n- item two")
+ .unwrap();
+ f.examples(&mut sink, "a();\nif (x) {\n b();\n}").unwrap();
+ f.notes(&mut sink, "Note one.\n\nNote two.").unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_plain(&mut f, &mut sink);
+ assert!(out
+ .contains("Detailed Description:\n First paragraph.\n\n - item one\n - item two\n"));
+ assert!(out.contains("Examples:\n a();\n if (x) {\n b();\n }\n"));
+ assert!(out.contains("Notes:\n Note one.\n\n Note two.\n"));
+ }
+}
diff --git a/tools/kapi/src/formatter/rst.rs b/tools/kapi/src/formatter/rst.rs
new file mode 100644
index 0000000000000..c208d876c9777
--- /dev/null
+++ b/tools/kapi/src/formatter/rst.rs
@@ -0,0 +1,802 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+use super::OutputFormatter;
+use crate::extractor::{
+ CapabilitySpec, ConstraintSpec, ErrorSpec, LockSpec, ParamSpec, ReturnSpec, SideEffectSpec,
+ SignalMaskSpec, SignalSpec, StateTransitionSpec,
+};
+use std::io::Write;
+
+pub struct RstFormatter;
+
+impl RstFormatter {
+ pub fn new() -> Self {
+ RstFormatter
+ }
+
+ fn section_char(level: usize) -> char {
+ match level {
+ 0 => '=',
+ 1 => '-',
+ 2 => '~',
+ 3 => '^',
+ _ => '"',
+ }
+ }
+}
+
+impl OutputFormatter for RstFormatter {
+ fn begin_document(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn end_document(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_api_list(&mut self, w: &mut dyn Write, title: &str) -> std::io::Result<()> {
+ writeln!(w, "\n{title}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(0).to_string().repeat(title.len())
+ )?;
+ writeln!(w)
+ }
+
+ fn api_item(&mut self, w: &mut dyn Write, name: &str, api_type: &str) -> std::io::Result<()> {
+ writeln!(w, "* **{name}** (*{api_type}*)")
+ }
+
+ fn end_api_list(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn total_specs(&mut self, w: &mut dyn Write, count: usize) -> std::io::Result<()> {
+ writeln!(w, "\n**Total specifications found:** {count}")
+ }
+
+ fn begin_api_details(&mut self, w: &mut dyn Write, name: &str) -> std::io::Result<()> {
+ writeln!(w, "\n{name}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(0).to_string().repeat(name.len())
+ )?;
+ writeln!(w)
+ }
+
+ fn end_api_details(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn description(&mut self, w: &mut dyn Write, desc: &str) -> std::io::Result<()> {
+ writeln!(w, "**{desc}**")?;
+ writeln!(w)
+ }
+
+ fn long_description(&mut self, w: &mut dyn Write, desc: &str) -> std::io::Result<()> {
+ writeln!(w, "{}", super::rst_text(desc))?;
+ writeln!(w)
+ }
+
+ fn begin_context_flags(&mut self, w: &mut dyn Write) -> std::io::Result<()> {
+ let title = "Execution Context";
+ writeln!(w, "{title}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(1).to_string().repeat(title.len())
+ )?;
+ writeln!(w)
+ }
+
+ fn context_flag(&mut self, w: &mut dyn Write, flag: &str) -> std::io::Result<()> {
+ writeln!(w, "* {flag}")
+ }
+
+ fn end_context_flags(&mut self, w: &mut dyn Write) -> std::io::Result<()> {
+ writeln!(w)
+ }
+
+ fn begin_parameters(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ let title = format!("Parameters ({count})");
+ writeln!(w, "{title}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(1).to_string().repeat(title.len())
+ )?;
+ writeln!(w)
+ }
+
+ fn end_parameters(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_errors(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ let title = format!("Possible Errors ({count})");
+ writeln!(w, "{title}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(1).to_string().repeat(title.len())
+ )?;
+ writeln!(w)
+ }
+
+ fn end_errors(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn examples(&mut self, w: &mut dyn Write, examples: &str) -> std::io::Result<()> {
+ let title = "Examples";
+ writeln!(w, "{title}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(1).to_string().repeat(title.len())
+ )?;
+ writeln!(w)?;
+ writeln!(w, ".. code-block:: c")?;
+ writeln!(w)?;
+ super::write_indented(w, " ", examples)?;
+ writeln!(w)
+ }
+
+ fn notes(&mut self, w: &mut dyn Write, notes: &str) -> std::io::Result<()> {
+ let title = "Notes";
+ writeln!(w, "{title}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(1).to_string().repeat(title.len())
+ )?;
+ writeln!(w)?;
+ writeln!(w, "{}", super::rst_text(notes))?;
+ writeln!(w)
+ }
+
+ fn sysfs_subsystem(&mut self, w: &mut dyn Write, subsystem: &str) -> std::io::Result<()> {
+ writeln!(w, ":Subsystem: {subsystem}")?;
+ writeln!(w)
+ }
+
+ fn sysfs_path(&mut self, w: &mut dyn Write, path: &str) -> std::io::Result<()> {
+ writeln!(w, ":Sysfs Path: {path}")?;
+ writeln!(w)
+ }
+
+ fn sysfs_permissions(&mut self, w: &mut dyn Write, perms: &str) -> std::io::Result<()> {
+ writeln!(w, ":Permissions: {perms}")?;
+ writeln!(w)
+ }
+
+ fn begin_capabilities(&mut self, w: &mut dyn Write) -> std::io::Result<()> {
+ let title = "Required Capabilities";
+ writeln!(w, "{title}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(1).to_string().repeat(title.len())
+ )?;
+ writeln!(w)
+ }
+
+ fn capability(&mut self, w: &mut dyn Write, cap: &CapabilitySpec) -> std::io::Result<()> {
+ writeln!(w, "**{} ({})** - {}", cap.name, cap.capability, cap.action)?;
+ writeln!(w)?;
+ if !cap.allows.is_empty() {
+ writeln!(w, "* **Allows:** {}", cap.allows)?;
+ }
+ if !cap.without_cap.is_empty() {
+ writeln!(w, "* **Without capability:** {}", cap.without_cap)?;
+ }
+ if let Some(cond) = &cap.check_condition {
+ writeln!(w, "* **Condition:** {}", cond)?;
+ }
+ writeln!(w)
+ }
+
+ fn end_capabilities(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn parameter(&mut self, w: &mut dyn Write, param: &ParamSpec) -> std::io::Result<()> {
+ writeln!(
+ w,
+ "**[{}] {}** (*{}*)",
+ param.index, param.name, param.type_name
+ )?;
+ writeln!(w)?;
+ writeln!(w, " {}", param.description)?;
+
+ // Display flags
+ let flags = super::param_flag_names(param.flags);
+ if !flags.is_empty() {
+ writeln!(w, " :Flags: {}", flags.join(", "))?;
+ }
+
+ if let Some(constraint) = ¶m.constraint {
+ writeln!(w, " :Constraint: {}", constraint)?;
+ }
+
+ if let Some(range) = super::range_text(param.min_value, param.max_value) {
+ writeln!(w, " :Range: {}", range)?;
+ }
+
+ writeln!(w)
+ }
+
+ fn return_spec(&mut self, w: &mut dyn Write, ret: &ReturnSpec) -> std::io::Result<()> {
+ writeln!(w, "\nReturn Value")?;
+ writeln!(w, "{}\n", Self::section_char(1).to_string().repeat(12))?;
+ writeln!(w)?;
+ writeln!(w, ":Type: {}", ret.type_name)?;
+ writeln!(w, ":Description: {}", ret.description)?;
+ if let Some(success) = ret.success_value {
+ writeln!(w, ":Success value: {}", success)?;
+ }
+ writeln!(w)
+ }
+
+ fn error(&mut self, w: &mut dyn Write, error: &ErrorSpec) -> std::io::Result<()> {
+ writeln!(w, "**{}** ({})", error.name, error.error_code)?;
+ writeln!(w)?;
+ writeln!(w, " :Condition: {}", error.condition)?;
+ if !error.description.is_empty() {
+ writeln!(w, " :Description: {}", error.description)?;
+ }
+ writeln!(w)
+ }
+
+ fn begin_signals(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ let title = format!("Signals ({count})");
+ writeln!(w, "{title}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(1).to_string().repeat(title.len())
+ )?;
+ writeln!(w)
+ }
+
+ fn signal(&mut self, w: &mut dyn Write, signal: &SignalSpec) -> std::io::Result<()> {
+ write!(w, "* **{}**", signal.signal_name)?;
+ if signal.signal_num != 0 {
+ write!(w, " ({})", signal.signal_num)?;
+ }
+ writeln!(w)?;
+
+ // Direction (bitmask matching C enum kapi_signal_direction)
+ let mut dirs = Vec::new();
+ if signal.direction & 1 != 0 {
+ dirs.push("receive");
+ }
+ if signal.direction & 2 != 0 {
+ dirs.push("send");
+ }
+ if signal.direction & 4 != 0 {
+ dirs.push("handle");
+ }
+ if signal.direction & 8 != 0 {
+ dirs.push("block");
+ }
+ if signal.direction & 16 != 0 {
+ dirs.push("ignore");
+ }
+ let direction = if dirs.is_empty() {
+ "unknown".to_string()
+ } else {
+ dirs.join(", ")
+ };
+ writeln!(w, " :Direction: {}", direction)?;
+
+ // Action (matching C enum kapi_signal_action)
+ let action = match signal.action {
+ 0 => "default",
+ 1 => "terminate",
+ 2 => "coredump",
+ 3 => "stop",
+ 4 => "continue",
+ 5 => "custom",
+ 6 => "return",
+ 7 => "restart",
+ 8 => "queue",
+ 9 => "discard",
+ 10 => "transform",
+ _ => "unknown",
+ };
+ writeln!(w, " :Action: {}", action)?;
+
+ if let Some(target) = &signal.target {
+ writeln!(w, " :Target: {}", target)?;
+ }
+ if let Some(cond) = &signal.condition {
+ writeln!(w, " :Condition: {}", cond)?;
+ }
+ if let Some(desc) = &signal.description {
+ writeln!(w, " :Description: {}", desc)?;
+ }
+ let timing = match signal.timing {
+ 0 => "before",
+ 1 => "during",
+ 2 => "after",
+ 3 => "exit",
+ _ => "",
+ };
+ if !timing.is_empty() {
+ writeln!(w, " :Timing: {}", timing)?;
+ }
+ if signal.priority != 0 {
+ writeln!(w, " :Priority: {}", signal.priority)?;
+ }
+ if signal.interruptible {
+ writeln!(w, " :Interruptible: yes")?;
+ }
+ if signal.restartable {
+ writeln!(w, " :Restartable: yes")?;
+ }
+ if let Some(queue) = &signal.queue {
+ writeln!(w, " :Queue: {}", queue)?;
+ }
+ if signal.sa_flags_required != 0 {
+ writeln!(w, " :SA flags required: {:#x}", signal.sa_flags_required)?;
+ }
+ if signal.sa_flags_forbidden != 0 {
+ writeln!(w, " :SA flags forbidden: {:#x}", signal.sa_flags_forbidden)?;
+ }
+ if signal.state_required != 0 {
+ writeln!(w, " :State required: {:#x}", signal.state_required)?;
+ }
+ if signal.state_forbidden != 0 {
+ writeln!(w, " :State forbidden: {:#x}", signal.state_forbidden)?;
+ }
+ if let Some(error) = signal.error_on_signal {
+ writeln!(w, " :Error on signal: {}", error)?;
+ }
+ if let Some(transform) = signal.transform_to {
+ writeln!(w, " :Transform to: {}", transform)?;
+ }
+ writeln!(w)
+ }
+
+ fn end_signals(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_signal_masks(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ let title = format!("Signal Masks ({count})");
+ writeln!(w, "{title}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(1).to_string().repeat(title.len())
+ )?;
+ writeln!(w)
+ }
+
+ fn signal_mask(&mut self, w: &mut dyn Write, mask: &SignalMaskSpec) -> std::io::Result<()> {
+ writeln!(w, "* **{}**", mask.name)?;
+ if !mask.description.is_empty() {
+ writeln!(w, " {}", mask.description)?;
+ }
+ if !mask.signals.is_empty() {
+ let signals: Vec<String> = mask.signals.iter().map(i32::to_string).collect();
+ writeln!(w, " Signals: {}", signals.join(", "))?;
+ }
+ writeln!(w)
+ }
+
+ fn end_signal_masks(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_side_effects(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ let title = format!("Side Effects ({count})");
+ writeln!(w, "{}\n", title)?;
+ writeln!(
+ w,
+ "{}\n",
+ Self::section_char(1).to_string().repeat(title.len())
+ )
+ }
+
+ fn side_effect(&mut self, w: &mut dyn Write, effect: &SideEffectSpec) -> std::io::Result<()> {
+ write!(w, "* **{}**", effect.target)?;
+ if effect.reversible {
+ write!(w, " *(reversible)*")?;
+ }
+ writeln!(w)?;
+ writeln!(w, " {}", effect.description)?;
+ if let Some(cond) = &effect.condition {
+ writeln!(w, " :Condition: {}", cond)?;
+ }
+ writeln!(w)
+ }
+
+ fn end_side_effects(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_state_transitions(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ let title = format!("State Transitions ({count})");
+ writeln!(w, "{}\n", title)?;
+ writeln!(
+ w,
+ "{}\n",
+ Self::section_char(1).to_string().repeat(title.len())
+ )
+ }
+
+ fn state_transition(
+ &mut self,
+ w: &mut dyn Write,
+ trans: &StateTransitionSpec,
+ ) -> std::io::Result<()> {
+ writeln!(
+ w,
+ "* **{}**: {} → {}",
+ trans.object, trans.from_state, trans.to_state
+ )?;
+ writeln!(w, " {}", trans.description)?;
+ if let Some(cond) = &trans.condition {
+ writeln!(w, " :Condition: {}", cond)?;
+ }
+ writeln!(w)
+ }
+
+ fn end_state_transitions(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_constraints(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ let title = format!("Constraints ({count})");
+ writeln!(w, "{title}")?;
+ writeln!(
+ w,
+ "{}",
+ Self::section_char(1).to_string().repeat(title.len())
+ )?;
+ writeln!(w)
+ }
+
+ fn constraint(
+ &mut self,
+ w: &mut dyn Write,
+ constraint: &ConstraintSpec,
+ ) -> std::io::Result<()> {
+ writeln!(w, "* **{}**", constraint.name)?;
+ if !constraint.description.is_empty() {
+ writeln!(w, " {}", constraint.description)?;
+ }
+ if let Some(expr) = &constraint.expression {
+ writeln!(w, " :Expression: ``{}``", expr)?;
+ }
+ writeln!(w)
+ }
+
+ fn end_constraints(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_locks(&mut self, w: &mut dyn Write, count: u32) -> std::io::Result<()> {
+ let title = format!("Locks ({count})");
+ writeln!(w, "{}\n", title)?;
+ writeln!(
+ w,
+ "{}\n",
+ Self::section_char(1).to_string().repeat(title.len())
+ )
+ }
+
+ fn lock(&mut self, w: &mut dyn Write, lock: &LockSpec) -> std::io::Result<()> {
+ write!(w, "* **{}**", lock.lock_name)?;
+ let lock_type_str = match lock.lock_type {
+ 1 => " *(mutex)*",
+ 2 => " *(spinlock)*",
+ 3 => " *(rwlock)*",
+ 4 => " *(seqlock)*",
+ 5 => " *(RCU)*",
+ 6 => " *(semaphore)*",
+ 7 => " *(custom)*",
+ _ => "",
+ };
+ writeln!(w, "{}", lock_type_str)?;
+ if !lock.description.is_empty() {
+ writeln!(w, " {}", lock.description)?;
+ }
+ writeln!(w)
+ }
+
+ fn end_locks(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+
+ fn begin_struct_specs(&mut self, w: &mut dyn Write, _count: u32) -> std::io::Result<()> {
+ writeln!(w)?;
+ writeln!(w, "Structure Specifications")?;
+ writeln!(w, "~~~~~~~~~~~~~~~~~~~~~~~")?;
+ writeln!(w)
+ }
+
+ fn struct_spec(
+ &mut self,
+ w: &mut dyn Write,
+ spec: &crate::extractor::StructSpec,
+ ) -> std::io::Result<()> {
+ writeln!(w, "**{}**", spec.name)?;
+ writeln!(w)?;
+
+ if !spec.description.is_empty() {
+ writeln!(w, " {}", spec.description)?;
+ writeln!(w)?;
+ }
+
+ writeln!(w, " :Size: {} bytes", spec.size)?;
+ writeln!(w, " :Alignment: {} bytes", spec.alignment)?;
+ writeln!(w, " :Fields: {}", spec.field_count)?;
+ writeln!(w)?;
+
+ if !spec.fields.is_empty() {
+ for field in &spec.fields {
+ writeln!(w, " * **{}** ({})", field.name, field.type_name)?;
+ if !field.description.is_empty() {
+ writeln!(w, " {}", field.description)?;
+ }
+ if field.min_value != 0 || field.max_value != 0 {
+ writeln!(w, " Range: [{}, {}]", field.min_value, field.max_value)?;
+ }
+ }
+ writeln!(w)?;
+ }
+
+ Ok(())
+ }
+
+ fn end_struct_specs(&mut self, _w: &mut dyn Write) -> std::io::Result<()> {
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::extractor::{ErrorSpec, LockSpec, ParamSpec, ReturnSpec};
+
+ fn render_rst(f: &mut RstFormatter, sink: &mut Vec<u8>) -> String {
+ f.end_document(sink).unwrap();
+ String::from_utf8(sink.clone()).unwrap()
+ }
+
+ #[test]
+ fn rst_api_details_has_heading() {
+ let mut f = RstFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.description(&mut sink, "A test syscall").unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_rst(&mut f, &mut sink);
+ assert!(out.contains("sys_test"));
+ assert!(out.contains("========"));
+ assert!(out.contains("**A test syscall**"));
+ }
+
+ #[test]
+ fn rst_api_list() {
+ let mut f = RstFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_list(&mut sink, "System Calls").unwrap();
+ f.api_item(&mut sink, "sys_open", "syscall").unwrap();
+ f.api_item(&mut sink, "sys_read", "syscall").unwrap();
+ f.end_api_list(&mut sink).unwrap();
+ f.total_specs(&mut sink, 2).unwrap();
+
+ let out = render_rst(&mut f, &mut sink);
+ assert!(out.contains("sys_open"));
+ assert!(out.contains("sys_read"));
+ }
+
+ #[test]
+ fn rst_parameters() {
+ let mut f = RstFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_write").unwrap();
+ f.begin_parameters(&mut sink, 1).unwrap();
+ f.parameter(
+ &mut sink,
+ &ParamSpec {
+ index: 0,
+ name: "fd".to_string(),
+ type_name: "unsigned int".to_string(),
+ description: "file descriptor".to_string(),
+ flags: 1,
+ param_type: 2,
+ constraint_type: 0,
+ constraint: None,
+ min_value: None,
+ max_value: None,
+ valid_mask: None,
+ enum_values: vec![],
+ size: None,
+ alignment: None,
+ size_param_idx: None,
+ },
+ )
+ .unwrap();
+ f.end_parameters(&mut sink).unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_rst(&mut f, &mut sink);
+ assert!(out.contains("**[0] fd**"));
+ assert!(out.contains("unsigned int"));
+ assert!(out.contains("file descriptor"));
+ }
+
+ #[test]
+ fn rst_errors() {
+ let mut f = RstFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.begin_errors(&mut sink, 1).unwrap();
+ f.error(
+ &mut sink,
+ &ErrorSpec {
+ error_code: -2,
+ name: "ENOENT".to_string(),
+ condition: "File not found".to_string(),
+ description: "The file does not exist".to_string(),
+ },
+ )
+ .unwrap();
+ f.end_errors(&mut sink).unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_rst(&mut f, &mut sink);
+ assert!(out.contains("**ENOENT**"));
+ assert!(out.contains("-2"));
+ assert!(out.contains("File not found"));
+ }
+
+ #[test]
+ fn rst_return_spec() {
+ let mut f = RstFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.return_spec(
+ &mut sink,
+ &ReturnSpec {
+ type_name: "KAPI_TYPE_INT".to_string(),
+ description: "Returns 0 on success".to_string(),
+ return_type: 1,
+ check_type: 0,
+ success_value: Some(0),
+ success_min: None,
+ success_max: None,
+ error_values: vec![],
+ },
+ )
+ .unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_rst(&mut f, &mut sink);
+ assert!(out.contains("KAPI_TYPE_INT"));
+ assert!(out.contains("Returns 0 on success"));
+ assert!(out.contains("Return Value"));
+ }
+
+ #[test]
+ fn rst_context_flags() {
+ let mut f = RstFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.begin_context_flags(&mut sink).unwrap();
+ f.context_flag(&mut sink, "KAPI_CTX_PROCESS").unwrap();
+ f.context_flag(&mut sink, "KAPI_CTX_SLEEPABLE").unwrap();
+ f.end_context_flags(&mut sink).unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_rst(&mut f, &mut sink);
+ assert!(out.contains("KAPI_CTX_PROCESS"));
+ assert!(out.contains("KAPI_CTX_SLEEPABLE"));
+ assert!(out.contains("Execution Context"));
+ }
+
+ #[test]
+ fn rst_signal_mask_lists_its_signals() {
+ let mut f = RstFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.begin_signal_masks(&mut sink, 1).unwrap();
+ f.signal_mask(
+ &mut sink,
+ &SignalMaskSpec {
+ name: "blocked".to_string(),
+ description: "Blocked while running".to_string(),
+ signals: vec![2, 15],
+ },
+ )
+ .unwrap();
+ f.end_signal_masks(&mut sink).unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_rst(&mut f, &mut sink);
+ assert!(out.contains("* **blocked**\n Blocked while running\n Signals: 2, 15\n"));
+ }
+
+ #[test]
+ fn rst_examples_are_a_literal_block_with_blank_lines_kept() {
+ let mut f = RstFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.examples(&mut sink, "a();\n b();\n\nc();").unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_rst(&mut f, &mut sink);
+ assert!(out.contains(".. code-block:: c\n\n a();\n b();\n\n c();\n"));
+ }
+
+ #[test]
+ fn rst_bullets_get_blank_lines_around_the_list() {
+ let mut f = RstFormatter::new();
+ let mut sink = Vec::new();
+
+ f.begin_document(&mut sink).unwrap();
+ f.begin_api_details(&mut sink, "sys_test").unwrap();
+ f.long_description(&mut sink, "Intro:\n- one\n- two\n\nTail.")
+ .unwrap();
+ f.notes(&mut sink, "Para one.\n\n- a\n- b\nafter").unwrap();
+ f.end_api_details(&mut sink).unwrap();
+
+ let out = render_rst(&mut f, &mut sink);
+ assert!(out.contains("Intro:\n\n- one\n- two\n\nTail.\n"));
+ assert!(out.contains("Para one.\n\n- a\n- b\n\nafter\n"));
+ }
+
+ #[test]
+ fn rst_lock_types_follow_the_kernel_enum() {
+ let mut f = RstFormatter::new();
+ let mut sink = Vec::new();
+
+ for (lock_type, label) in [
+ (1, "mutex"),
+ (2, "spinlock"),
+ (3, "rwlock"),
+ (4, "seqlock"),
+ (5, "RCU"),
+ (6, "semaphore"),
+ (7, "custom"),
+ ] {
+ f.lock(
+ &mut sink,
+ &LockSpec {
+ lock_name: "l".to_string(),
+ lock_type,
+ scope: 0,
+ description: String::new(),
+ },
+ )
+ .unwrap();
+ let out = String::from_utf8(std::mem::take(&mut sink)).unwrap();
+ assert_eq!(out, format!("* **l** *({label})*\n\n"));
+ }
+ }
+}
diff --git a/tools/kapi/src/main.rs b/tools/kapi/src/main.rs
new file mode 100644
index 0000000000000..93ed11b508e9f
--- /dev/null
+++ b/tools/kapi/src/main.rs
@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+
+//! kapi - Kernel API Specification Tool
+//!
+//! This tool extracts and displays kernel API specifications from multiple sources:
+//! - Kernel source code (kerneldoc blocks)
+//! - Compiled vmlinux binaries (`.kapi_specs` ELF section)
+//! - Running kernel via debugfs
+
+use anyhow::Result;
+use clap::Parser;
+use std::io::{self, Write};
+
+mod extractor;
+mod formatter;
+
+use extractor::{ApiExtractor, DebugfsExtractor, SourceExtractor, VmlinuxExtractor};
+use formatter::{create_formatter, OutputFormat};
+
+#[derive(Parser, Debug)]
+#[command(author, version, about, long_about = None)]
+struct Args {
+ /// Path to the vmlinux file
+ #[arg(long, value_name = "PATH", group = "input")]
+ vmlinux: Option<String>,
+
+ /// Path to kernel source directory or file
+ #[arg(long, value_name = "PATH", group = "input")]
+ source: Option<String>,
+
+ /// Path to debugfs (defaults to /sys/kernel/debug if not specified)
+ #[arg(long, value_name = "PATH", group = "input")]
+ debugfs: Option<String>,
+
+ /// Optional: Name of specific API to show details for
+ api_name: Option<String>,
+
+ /// Output format
+ #[arg(long, short = 'f', default_value = "plain")]
+ format: String,
+}
+
+fn main() -> Result<()> {
+ let args = Args::parse();
+
+ let output_format: OutputFormat = args
+ .format
+ .parse()
+ .map_err(|e: String| anyhow::anyhow!(e))?;
+
+ let extractor: Box<dyn ApiExtractor> = match (&args.vmlinux, &args.source, &args.debugfs) {
+ (Some(vmlinux_path), None, None) => Box::new(VmlinuxExtractor::new(vmlinux_path)?),
+ (None, Some(source_path), None) => Box::new(SourceExtractor::new(source_path)?),
+ (None, None, Some(_) | None) => {
+ // If debugfs is specified or no input is provided, use debugfs
+ Box::new(DebugfsExtractor::new(args.debugfs.clone())?)
+ }
+ _ => {
+ anyhow::bail!("Please specify only one of --vmlinux, --source, or --debugfs")
+ }
+ };
+
+ display_apis(extractor.as_ref(), args.api_name, output_format)
+}
+
+fn display_apis(
+ extractor: &dyn ApiExtractor,
+ api_name: Option<String>,
+ output_format: OutputFormat,
+) -> Result<()> {
+ let mut formatter = create_formatter(output_format);
+ let mut stdout = io::stdout();
+
+ formatter.begin_document(&mut stdout)?;
+
+ if let Some(api_name_req) = api_name {
+ // Use the extractor to display API details
+ if let Some(_spec) = extractor.extract_by_name(&api_name_req)? {
+ extractor.display_api_details(&api_name_req, &mut *formatter, &mut stdout)?;
+ } else {
+ eprintln!("API '{}' not found.", api_name_req);
+ if output_format == OutputFormat::Plain {
+ writeln!(stdout, "\nAvailable APIs:")?;
+ for spec in extractor.extract_all()? {
+ writeln!(stdout, " {} ({})", spec.name, spec.api_type)?;
+ }
+ }
+ std::process::exit(1);
+ }
+ } else {
+ // Display list of APIs using the extractor
+ let all_specs = extractor.extract_all()?;
+
+ // Helper to display API list for a specific type
+ let mut display_api_type = |api_type: &str, title: &str| -> Result<()> {
+ let filtered: Vec<_> = all_specs
+ .iter()
+ .filter(|s| s.api_type == api_type)
+ .collect();
+
+ if !filtered.is_empty() {
+ formatter.begin_api_list(&mut stdout, title)?;
+ for spec in filtered {
+ formatter.api_item(&mut stdout, &spec.name, &spec.api_type)?;
+ }
+ formatter.end_api_list(&mut stdout)?;
+ }
+ Ok(())
+ };
+
+ display_api_type("syscall", "System Calls")?;
+ display_api_type("ioctl", "IOCTLs")?;
+ display_api_type("function", "Functions")?;
+ display_api_type("sysfs", "Sysfs Attributes")?;
+
+ formatter.total_specs(&mut stdout, all_specs.len())?;
+ }
+
+ formatter.end_document(&mut stdout)?;
+
+ Ok(())
+}
--
2.53.0
next prev parent reply other threads:[~2026-10-08 8:50 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-10-08 8:49 [PATCH v5 00/11] Kernel API Specification Framework Sasha Levin
2026-10-08 8:49 ` [PATCH v5 01/11] kernel/api: introduce kernel API specification framework Sasha Levin
2026-10-08 8:49 ` [PATCH v5 02/11] kernel/api: enable kerneldoc-based API specifications Sasha Levin
2026-10-08 8:49 ` [PATCH v5 03/11] kernel/api: add debugfs interface for kernel " Sasha Levin
2026-10-08 8:49 ` Sasha Levin [this message]
2026-10-08 8:49 ` [PATCH v5 05/11] kernel/api: add API specification for sys_open Sasha Levin
2026-10-08 12:49 ` Serge E. Hallyn
2026-10-08 13:13 ` Gregory Price
2026-10-08 14:20 ` Serge E. Hallyn
2026-10-08 14:37 ` Sasha Levin
2026-10-08 14:46 ` Serge E. Hallyn
2026-10-08 15:23 ` Sasha Levin
2026-10-08 16:12 ` David Laight
2026-10-08 16:16 ` Serge E. Hallyn
2026-10-08 22:47 ` Sasha Levin
2026-10-08 8:49 ` [PATCH v5 06/11] kernel/api: add API specification for sys_close Sasha Levin
2026-10-08 8:49 ` [PATCH v5 07/11] kernel/api: add API specification for sys_read Sasha Levin
2026-10-08 8:49 ` [PATCH v5 08/11] kernel/api: add API specification for sys_write Sasha Levin
2026-10-08 8:49 ` [PATCH v5 09/11] kernel/api: add runtime verification selftest Sasha Levin
2026-10-08 8:49 ` [PATCH v5 10/11] kernel/api: add API specification for sys_madvise Sasha Levin
2026-10-08 8:49 ` [PATCH v5 11/11] kernel/api: add syscall enter/exit tracepoints 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=20261008084956.2911790-5-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=mathieu.desnoyers@efficios.com \
--cc=mchehab@kernel.org \
--cc=mhiramat@kernel.org \
--cc=nathan@kernel.org \
--cc=paulmck@kernel.org \
--cc=rdunlap@infradead.org \
--cc=rostedt@goodmis.org \
--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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.