Kernel API Specification Framework
Subsystems (11)
v4 cover Kernel API Specification Framework
This patch series introduces a framework for formally specifying kernel APIs, addressing the long-standing challenge of maintaining stable interfaces between the kernel and user-space programs. As outlined in previous discussions about kernel ABI stability, the lack of machine-readable API specifications has led to inadvertent breakages and inconsistent validation across system calls and IOCTLs.
Changes since RFC v3:
1. Improved kerneldoc format for better readability.
2. Added kerneldoc parsing support in the kapi tool.
3. Use magic markers in the binary output to simplify extraction.
Sasha Levin (7):
kernel/api: introduce kernel API specification framework kernel/api: enable kerneldoc-based API specifications kernel/api: add debugfs interface for kernel API specifications kernel/sched: add specs for sys_sched_setattr() mm/mlock: add API specification for mlock
fs/exec: add API specification for execveat tools/kapi: Add kernel API specification extraction tool
.gitignore | 1 + Documentation/admin-guide/kernel-api-spec.rst | 699 ++++++++ MAINTAINERS | 9 + arch/um/kernel/dyn.lds.S | 3 + arch/um/kernel/uml.lds.S | 3 + arch/x86/kernel/vmlinux.lds.S | 3 + fs/exec.c | 594 +++++++ include/asm-generic/vmlinux.lds.h | 20 + include/linux/kernel_api_spec.h | 1559 +++++++++++++++++ include/linux/syscall_api_spec.h | 125 ++ include/linux/syscalls.h | 38 + init/Kconfig | 2 + kernel/Makefile | 1 + kernel/api/Kconfig | 55 + kernel/api/Makefile | 30 + kernel/api/kapi_debugfs.c | 334 ++++ kernel/api/kernel_api_spec.c | 1155 ++++++++++++ kernel/sched/syscalls.c | 315 +++- mm/mlock.c | 134 ++ scripts/Makefile.build | 28 + scripts/generate_api_specs.sh | 68 + scripts/kernel-doc.py | 5 + scripts/lib/kdoc/kdoc_apispec.py | 714 ++++++++ scripts/lib/kdoc/kdoc_output.py | 9 +- scripts/lib/kdoc/kdoc_parser.py | 50 +- tools/kapi/.gitignore | 4 + tools/kapi/Cargo.toml | 19 + tools/kapi/src/extractor/debugfs.rs | 442 +++++ tools/kapi/src/extractor/kerneldoc_parser.rs | 694 ++++++++ tools/kapi/src/extractor/mod.rs | 461 +++++ tools/kapi/src/extractor/source_parser.rs | 213 +++ .../src/extractor/vmlinux/binary_utils.rs | 180 ++ .../src/extractor/vmlinux/magic_finder.rs | 102 ++ tools/kapi/src/extractor/vmlinux/mod.rs | 869 +++++++++ tools/kapi/src/formatter/json.rs | 468 +++++ tools/kapi/src/formatter/mod.rs | 145 ++ tools/kapi/src/formatter/plain.rs | 558 ++++++ tools/kapi/src/formatter/rst.rs | 621 +++++++ tools/kapi/src/formatter/shall.rs | 891 ++++++++++ tools/kapi/src/main.rs | 116 ++ 40 files changed, 11732 insertions(+), 5 deletions(-) create mode 100644 Documentation/admin-guide/kernel-api-spec.rst create mode 100644 include/linux/kernel_api_spec.h create mode 100644 include/linux/syscall_api_spec.h create mode 100644 kernel/api/Kconfig create mode 100644 kernel/api/Makefile create mode 100644 kernel/api/kapi_debugfs.c create mode 100644 kernel/api/kernel_api_spec.c create mode 100755 scripts/generate_api_specs.sh create mode 100644 scripts/lib/kdoc/kdoc_apispec.py create mode 100644 tools/kapi/.gitignore create mode 100644 tools/kapi/Cargo.toml create mode 100644 tools/kapi/src/extractor/debugfs.rs create mode 100644 tools/kapi/src/extractor/kerneldoc_parser.rs create mode 100644 tools/kapi/src/extractor/mod.rs create mode 100644 tools/kapi/src/extractor/source_parser.rs create mode 100644 tools/kapi/src/extractor/vmlinux/binary_utils.rs create mode 100644 tools/kapi/src/extractor/vmlinux/magic_finder.rs create mode 100644 tools/kapi/src/extractor/vmlinux/mod.rs create mode 100644 tools/kapi/src/formatter/json.rs create mode 100644 tools/kapi/src/formatter/mod.rs create mode 100644 tools/kapi/src/formatter/plain.rs create mode 100644 tools/kapi/src/formatter/rst.rs create mode 100644 tools/kapi/src/formatter/shall.rs create mode 100644 tools/kapi/src/main.rs
Signature · 1 line
2.50.1
RFC PATCH v4 1/7 kernel/api: introduce kernel API specification framework
Add a comprehensive framework for formally documenting kernel APIs with inline specifications. This framework provides:
- Structured API documentation with parameter specifications, return values, error conditions, and execution context requirements
- Runtime validation capabilities for debugging (CONFIG_KAPI_RUNTIME_CHECKS)
- Export of specifications via debugfs for tooling integration
- Support for both internal kernel APIs and system calls
The framework stores specifications in a dedicated ELF section and provides infrastructure for:
- Compile-time validation of specifications
- Runtime querying of API documentation
- Machine-readable export formats
- Integration with existing SYSCALL_DEFINE macros
This commit introduces the core infrastructure without modifying any existing APIs. Subsequent patches will add specifications to individual subsystems.
--- .gitignore | 1 + Documentation/admin-guide/kernel-api-spec.rst | 507 ++++++ MAINTAINERS | 9 + arch/um/kernel/dyn.lds.S | 3 + arch/um/kernel/uml.lds.S | 3 + arch/x86/kernel/vmlinux.lds.S | 3 + include/asm-generic/vmlinux.lds.h | 20 + include/linux/kernel_api_spec.h | 1559 +++++++++++++++++ include/linux/syscall_api_spec.h | 125 ++ include/linux/syscalls.h | 38 + init/Kconfig | 2 + kernel/Makefile | 1 + kernel/api/Kconfig | 35 + kernel/api/Makefile | 7 + kernel/api/kernel_api_spec.c | 1155 ++++++++++++ 15 files changed, 3468 insertions(+) create mode 100644 Documentation/admin-guide/kernel-api-spec.rst create mode 100644 include/linux/kernel_api_spec.h create mode 100644 include/linux/syscall_api_spec.h create mode 100644 kernel/api/Kconfig create mode 100644 kernel/api/Makefile create mode 100644 kernel/api/kernel_api_spec.c
.gitignore +1 -0
@@ -12,6 +12,7 @@ # .* *.a +*.apispec.h *.asn1.[ch] *.bin *.bz2
Documentation/admin-guide/kernel-api-spec.rst new file +507 -0
507 lines not on this page · raw message
MAINTAINERS +9 -0
@@ -13244,6 +13244,15 @@ W: https://linuxtv.org T: git git://linuxtv.org/media.git F: drivers/media/radio/radio-keene* +KERNEL API SPECIFICATION FRAMEWORK (KAPI) +M: Sasha Levin <[email protected]> +L: [email protected] +S: Maintained +F: Documentation/admin-guide/kernel-api-spec.rst +F: include/linux/kernel_api_spec.h +F: kernel/api/ +F: scripts/extract-kapi-spec.sh + KERNEL AUTOMOUNTER M: Ian Kent <[email protected]> L: [email protected]
arch/um/kernel/dyn.lds.S +3 -0
@@ -102,6 +102,9 @@ SECTIONS init.data : { INIT_DATA } __init_end = .; + /* Kernel API specifications in dedicated section */ + KAPI_SPECS_SECTION() + /* Ensure the __preinit_array_start label is properly aligned. We could instead move the label definition inside the section, but the linker would then create the section even if it turns out to
arch/um/kernel/uml.lds.S +3 -0
@@ -74,6 +74,9 @@ SECTIONS init.data : { INIT_DATA } __init_end = .; + /* Kernel API specifications in dedicated section */ + KAPI_SPECS_SECTION() + .data : { INIT_TASK_DATA(KERNEL_STACK_SIZE)
arch/x86/kernel/vmlinux.lds.S +3 -0
@@ -173,6 +173,9 @@ SECTIONS RO_DATA(PAGE_SIZE) X86_ALIGN_RODATA_END + /* Kernel API specifications in dedicated section */ + KAPI_SPECS_SECTION() + /* Data */ .data : AT(ADDR(.data) - LOAD_OFFSET) { /* Start of data section */
include/asm-generic/vmlinux.lds.h +20 -0
@@ -279,6 +279,26 @@ defined(CONFIG_AUTOFDO_CLANG) || defined(CONFIG_PROPELLER_CLANG)#define TRACE_SYSCALLS ()#endif +#ifdef CONFIG_KAPI_SPEC +#define KAPI_SPECS () \ + . = ALIGN(8); \ + __start_kapi_specs = .; \ + KEEP(*(.kapi_specs)) \ + __stop_kapi_specs = .; + +/* For placing KAPI specs in a dedicated section */ +#define KAPI_SPECS_SECTION () \ + .kapi_specs : AT(ADDR(.kapi_specs) - LOAD_OFFSET) { \ + . = ALIGN(8); \ + __start_kapi_specs = .; \ + KEEP(*(.kapi_specs)) \ + __stop_kapi_specs = .; \ + } +#else +#define KAPI_SPECS () +#define KAPI_SPECS_SECTION () +#endif +#ifdef CONFIG_BPF_EVENTS #define BPF_RAW_TP () STRUCT_ALIGN(); \ BOUNDED_SECTION_BY(__bpf_raw_tp_map, __bpf_raw_tp)
include/linux/kernel_api_spec.h new file +1559 -0
1,559 lines not on this page · raw message
include/linux/syscall_api_spec.h new file +125 -0
126 lines not on this page · raw message
include/linux/syscalls.h +38 -0
@@ -88,6 +88,7 @@ struct file_attr;#include <linux/bug.h> #include <linux/sem.h> #include <asm/siginfo.h> +#include <linux/syscall_api_spec.h> #include <linux/unistd.h> #include <linux/quota.h> #include <linux/key.h>
@@ -133,6 +134,7 @@ struct file_attr;#define __SC_TYPE (t, a) t#define __SC_ARGS (t, a) a#define __SC_TEST (t, a) (void)BUILD_BUG_ON_ZERO(!__TYPE_IS_LL(t) && sizeof(t) > sizeof(long)) +#define __SC_CAST_TO_S64 (t, a) (s64)(a)#ifdef CONFIG_FTRACE_SYSCALLS #define __SC_STR_ADECL (t, a) #a
@@ -243,6 +245,41 @@ static inline int is_syscall_trace_event(struct trace_event_call *tp_event)* done within __do_sys_*(). */ #ifndef __SYSCALL_DEFINEx +#ifdef CONFIG_KAPI_RUNTIME_CHECKS +#define __SYSCALL_DEFINEx (x, name, ...) \ + __diag_push(); \ + __diag_ignore(GCC, 8, "-Wattribute-alias", \ + "Type aliasing is used to sanitize syscall arguments");\ + asmlinkage long sys##name(__MAP(x,__SC_DECL,__VA_ARGS__)) \ + __attribute__((alias(__stringify(__se_sys##name)))); \ + ALLOW_ERROR_INJECTION(sys##name, ERRNO); \ + static inline long __do_sys##name(__MAP(x,__SC_DECL,__VA_ARGS__));\ + static inline long __do_kapi_sys##name(__MAP(x,__SC_DECL,__VA_ARGS__)); \ + asmlinkage long __se_sys##name(__MAP(x,__SC_LONG,__VA_ARGS__)); \ + asmlinkage long __se_sys##name(__MAP(x,__SC_LONG,__VA_ARGS__)) \ + { \ + long ret = __do_kapi_sys##name(__MAP(x,__SC_CAST,__VA_ARGS__));\ + __MAP(x,__SC_TEST,__VA_ARGS__); \ + __PROTECT(x, ret,__MAP(x,__SC_ARGS,__VA_ARGS__)); \ + return ret; \ + } \ + __diag_pop(); \ + static inline long __do_kapi_sys##name(__MAP(x,__SC_DECL,__VA_ARGS__))\ + { \ + const struct kernel_api_spec *__spec = kapi_get_spec("sys_" #name); \ + if (__spec) { \ + s64 __params[x] = { __MAP(x,__SC_CAST_TO_S64,__VA_ARGS__) }; \ + int __ret = kapi_validate_syscall_params(__spec, __params, x); \ + if (__ret) return __ret; \ + } \ + long ret = __do_sys##name(__MAP(x,__SC_ARGS,__VA_ARGS__)); \ + if (__spec) { \ + kapi_validate_syscall_return(__spec, (s64)ret); \ + } \ + return ret; \ + } \ + static inline long __do_sys##name(__MAP(x,__SC_DECL,__VA_ARGS__)) +#else /* !CONFIG_KAPI_RUNTIME_CHECKS */ #define __SYSCALL_DEFINEx (x, name, ...) \ __diag_push(); \ __diag_ignore(GCC, 8, "-Wattribute-alias", \
@@ -261,6 +298,7 @@ static inline int is_syscall_trace_event(struct trace_event_call *tp_event) } \__diag_pop (); \ static inline long __do_sys##name(__MAP(x,__SC_DECL,__VA_ARGS__)) +#endif /* CONFIG_KAPI_RUNTIME_CHECKS */ #endif /* __SYSCALL_DEFINEx */ /* For split 64-bit arguments on 32-bit architectures */
init/Kconfig +2 -0
@@ -2108,6 +2108,8 @@ config TRACEPOINTS source "kernel/Kconfig.kexec" +source "kernel/api/Kconfig" + endmenu # General setup source "arch/Kconfig"
kernel/Makefile +1 -0
@@ -56,6 +56,7 @@ obj-y += dma/ obj-y += entry/ obj-y += unwind/ obj-$(CONFIG_MODULES) += module/ +obj-$(CONFIG_KAPI_SPEC) += api/ obj-$(CONFIG_KCMP) += kcmp.o obj-$(CONFIG_FREEZER) += freezer.o
kernel/api/Kconfig new file +35 -0
@@ -0,0 +1,35 @@ +# SPDX-License-Identifier: GPL-2.0-only +# +# Kernel API Specification Framework Configuration +# + +config KAPI_SPEC + bool "Kernel API Specification Framework" + help + This option enables the kernel API specification framework, + which provides formal documentation of kernel APIs in both + human and machine-readable formats. + + The framework allows developers to document APIs inline with + their implementation, including parameter specifications, + return values, error conditions, locking requirements, and + execution context constraints. + + When enabled, API specifications can be queried at runtime + and exported in various formats (JSON, XML) through debugfs. + + If unsure, say N. + +config KAPI_RUNTIME_CHECKS + bool "Runtime API specification checks" + depends on KAPI_SPEC + depends on DEBUG_KERNEL + help + Enable runtime validation of API usage against specifications. + This includes checking execution context requirements, parameter + validation, and lock state verification. + + This adds overhead and should only be used for debugging and + development. The checks use WARN_ONCE to report violations. + + If unsure, say N.
kernel/api/Makefile new file +7 -0
@@ -0,0 +1,7 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Makefile for the Kernel API Specification Framework +# + +# Core API specification framework +obj-$(CONFIG_KAPI_SPEC) += kernel_api_spec.o
kernel/api/kernel_api_spec.c new file +1155 -0
613 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.50.1
Part of the diff is not shown here. View the raw message.
Randy Dunlap
reviewerRe: [RFC PATCH v4 1/7] kernel/api: introduce kernel API specification framework
Hi Sasha,
Quoted 16 lines · Sasha Levin
Add a comprehensive framework for formally documenting kernel APIs with inline specifications. This framework provides:
- Structured API documentation with parameter specifications, return values, error conditions, and execution context requirements
- Runtime validation capabilities for debugging (CONFIG_KAPI_RUNTIME_CHECKS)
- Export of specifications via debugfs for tooling integration
- Support for both internal kernel APIs and system callsThe framework stores specifications in a dedicated ELF section and provides infrastructure for:
- Compile-time validation of specifications
- Runtime querying of API documentation
- Machine-readable export formats
- Integration with existingSYSCALL_DEFINEmacros
Quoted 8 lines
This commit introduces the core infrastructure without modifying any existing APIs. Subsequent patches will add specifications to individual subsystems.
Signed-off-by Sasha Levin <[email protected]>--- .gitignore | 1 + Documentation/admin-guide/kernel-api-spec.rst | 507 ++++++
To me, none of this feels like Documentation/admin-guide/ material. I don't think that many sysadmins will be using it.
Maybe Documentation/dev-tools/ ?
Closer to developer material that admin?
Quoted 12 lines
MAINTAINERS | 9 + arch/um/kernel/dyn.lds.S | 3 + arch/um/kernel/uml.lds.S | 3 + arch/x86/kernel/vmlinux.lds.S | 3 + include/asm-generic/vmlinux.lds.h | 20 + include/linux/kernel_api_spec.h | 1559 +++++++++++++++++ include/linux/syscall_api_spec.h | 125 ++ include/linux/syscalls.h | 38 + init/Kconfig | 2 + kernel/Makefile | 1 + kernel/api/Kconfig | 35 + kernel/api/Makefile | 7 +
Quoted 8 lines
kernel/api/kernel_api_spec.c | 1155 ++++++++++++ 15 files changed, 3468 insertions(+) create mode 100644 Documentation/admin-guide/kernel-api-spec.rst create mode 100644 include/linux/kernel_api_spec.h create mode 100644 include/linux/syscall_api_spec.h create mode 100644 kernel/api/Kconfig create mode 100644 kernel/api/Makefile create mode 100644 kernel/api/kernel_api_spec.c
thanks.
Signature · 1 line
~Randy
RFC PATCH v4 2/7 kernel/api: enable kerneldoc-based API specifications
In reply to Sasha LevinThis patch adds support for extracting API specifications from kernel-doc comments and generating C macro invocations for the kernel API specification framework.
--- kernel/api/Makefile | 21 +- scripts/Makefile.build | 28 ++ scripts/generate_api_specs.sh | 69 +++ scripts/kernel-doc.py | 5 + scripts/lib/kdoc/kdoc_apispec.py | 714 +++++++++++++++++++++++++++++++ scripts/lib/kdoc/kdoc_output.py | 9 +- scripts/lib/kdoc/kdoc_parser.py | 50 ++- 7 files changed, 891 insertions(+), 5 deletions(-) create mode 100755 scripts/generate_api_specs.sh create mode 100644 scripts/lib/kdoc/kdoc_apispec.py
kernel/api/Makefile +20 -1
@@ -4,4 +4,23 @@ # # Core API specification framework -obj-$(CONFIG_KAPI_SPEC) += kernel_api_spec.o +obj-$(CONFIG_KAPI_SPEC) += kernel_api_spec.o + +# Auto-generated API specifications collector +ifeq ($(CONFIG_KAPI_SPEC),y) +obj-$(CONFIG_KAPI_SPEC) += generated_api_specs.o + +# Find all potential apispec files (this is evaluated at make time) +apispec-files := $(shell find $(objtree) -name "*.apispec.h" -type f 2>/dev/null) + +# Generate the collector file +# Note: FORCE ensures this is always regenerated to pick up new apispec files +$(obj)/generated_api_specs.c: $(srctree)/scripts/generate_api_specs.sh FORCE + $(Q)$(CONFIG_SHELL) $< $(srctree) $(objtree) > $@ + +targets += generated_api_specs.c +clean-files += generated_api_specs.c + +# Add explicit dependency on the generator script +$(obj)/generated_api_specs.o: $(obj)/generated_api_specs.c +endif
scripts/Makefile.build +28 -0
@@ -172,6 +172,34 @@ ifneq ($(KBUILD_EXTRA_WARN),) $< endif +# Generate API spec headers from kernel-doc comments +ifeq ($(CONFIG_KAPI_SPEC),y) +# Function to check if a file has API specifications +has-apispec = $(shell grep -qE '^\s*\*\s*(api-type|long-desc|context-flags|param-type|error-code|capability|signal|lock|side-effect|state-trans):' $(src)/$(1) 2>/dev/null && echo $(1)) + +# Get base names without directory prefix +c-objs-base := $(notdir $(real-obj-y) $(real-obj-m)) +# Filter to only .o files with corresponding .c source files +c-files := $(foreach o,$(c-objs-base),$(if $(wildcard $(src)/$(o:.o=.c)),$(o:.o=.c))) +# Also check for any additional .c files that contain API specs but are included +extra-c-files := $(shell find $(src) -maxdepth 1 -name "*.c" -exec grep -l '^\s*\*\s*\(api-type\|long-desc\|context-flags\|param-type\|error-code\|capability\|signal\|lock\|side-effect\|state-trans\):' {} \; 2>/dev/null | xargs -r basename -a) +# Combine both lists and remove duplicates +all-c-files := $(sort $(c-files) $(extra-c-files)) +# Only include files that actually have API specifications +apispec-files := $(foreach f,$(all-c-files),$(call has-apispec,$(f))) +# Generate apispec targets with proper directory prefix +apispec-y := $(addprefix $(obj)/,$(apispec-files:.c=.apispec.h)) +always-y += $(apispec-y) +targets += $(apispec-y) + +quiet_cmd_apispec = APISPEC $@ + cmd_apispec = PYTHONDONTWRITEBYTECODE=1 $(KERNELDOC) -apispec \ + $(KDOCFLAGS) $< > $@ 2>/dev/null || rm -f $@ + +$(obj)/%.apispec.h: $(src)/%.c FORCE + $(call if_changed,apispec) +endif + # Compile C sources (.c) # ---------------------------------------------------------------------------
scripts/generate_api_specs.sh new file +69 -0
69 lines not on this page · raw message
scripts/kernel-doc.py +5 -0
@@ -109,6 +109,7 @@ sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) from kdoc_files import KernelFiles # pylint: disable=C0413 from kdoc_output import RestFormat, ManFormat # pylint: disable=C0413 +from kdoc_apispec import ApiSpecFormat # pylint: disable=C0413 DESC = """ Read C language source or header FILEs, extract embedded documentation comments,
@@ -225,6 +226,8 @@ def main(): help="Output reStructuredText format (default).") out_fmt.add_argument("-N", "-none", "--none", action="store_true", help="Do not output documentation, only warnings.") + out_fmt.add_argument("-apispec", "--apispec", action="store_true", + help="Output C macro invocations for kernel API specifications.") # Output selection mutually-exclusive group
@@ -285,6 +288,8 @@ def main(): out_style = ManFormat(modulename=args.modulename) elif args.none: out_style = None + elif args.apispec: + out_style = ApiSpecFormat() else: out_style = RestFormat()
scripts/lib/kdoc/kdoc_apispec.py new file +714 -0
715 lines not on this page · raw message
scripts/lib/kdoc/kdoc_output.py +7 -2
@@ -124,8 +124,13 @@ class OutputFormat: Output warnings for identifiers that will be displayed. """ - for log_msg in args.warnings: - self.config.warning(log_msg) + warnings = args.get('warnings', []) + + for log_msg in warnings: + # Skip numeric warnings (line numbers) which are false positives + # from parameter-specific sections like "param-constraint: name, value" + if not isinstance(log_msg, int): + self.config.warning(log_msg) def check_doc(self, name, args): """Check if DOC should be output"""
scripts/lib/kdoc/kdoc_parser.py +48 -2
62 lines not on this page · raw message
Signature · 1 line
2.50.1
RFC PATCH v4 3/7 kernel/api: add debugfs interface for kernel API specifications
In reply to Sasha LevinAdd a debugfs interface to expose kernel API specifications at runtime. This allows tools and users to query the complete API specifications through the debugfs filesystem.
The interface provides:
- /sys/kernel/debug/kapi/list - lists all available API specifications
- /sys/kernel/debug/kapi/specs/<name> - detailed info for each API
Each specification file includes:
- Function name, version, and descriptions
- Execution context requirements and flags
- Parameter details with types, flags, and constraints
- Return value specifications and success conditions
- Error codes with descriptions and conditions
- Locking requirements and constraints
- Signal handling specifications
- Examples, notes, and deprecation status
This enables runtime introspection of kernel APIs for documentation tools, static analyzers, and debugging purposes.
--- kernel/api/Kconfig | 20 +++ kernel/api/Makefile | 6 +- kernel/api/kapi_debugfs.c | 334 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 359 insertions(+), 1 deletion(-) create mode 100644 kernel/api/kapi_debugfs.c
kernel/api/Kconfig +20 -0
@@ -33,3 +33,23 @@ config KAPI_RUNTIME_CHECKS development. The checks use WARN_ONCE to report violations. If unsure, say N. + +config KAPI_SPEC_DEBUGFS + bool "Export kernel API specifications via debugfs" + depends on KAPI_SPEC + depends on DEBUG_FS + help + This option enables exporting kernel API specifications through + the debugfs filesystem. When enabled, specifications can be + accessed at /sys/kernel/debug/kapi/. + + The debugfs interface provides: + - A list of all available API specifications + - Detailed information for each API including parameters, + return values, errors, locking requirements, and constraints + - Complete machine-readable representation of the specs + + This is useful for documentation tools, static analyzers, and + runtime introspection of kernel APIs. + + If unsure, say N.
kernel/api/Makefile +5 -1
@@ -10,6 +10,9 @@ obj-$(CONFIG_KAPI_SPEC) += kernel_api_spec.o ifeq ($(CONFIG_KAPI_SPEC),y) obj-$(CONFIG_KAPI_SPEC) += generated_api_specs.o +# Debugfs interface for kernel API specs +obj-$(CONFIG_KAPI_SPEC_DEBUGFS) += kapi_debugfs.o + # Find all potential apispec files (this is evaluated at make time) apispec-files := $(shell find $(objtree) -name "*.apispec.h" -type f 2>/dev/null)
@@ -23,4 +26,5 @@ clean-files += generated_api_specs.c # Add explicit dependency on the generator script $(obj)/generated_api_specs.o: $(obj)/generated_api_specs.c -endif +endif +
kernel/api/kapi_debugfs.c new file +334 -0
335 lines not on this page · raw message
Signature · 1 line
2.50.1
RFC PATCH v4 4/7 kernel/sched: add specs for sys_sched_setattr()
In reply to Sasha Levin--- kernel/sched/syscalls.c | 315 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 314 insertions(+), 1 deletion(-)
kernel/sched/syscalls.c +314 -1
@@ -969,10 +969,323 @@ SYSCALL_DEFINE2(sched_setparam, pid_t, pid, struct sched_param __user *, param) }/** -* sys_sched_setattr - same as above, but with extended sched_attr +* sys_sched_setattr - set/change scheduling policy and attributes * @pid: the pid in question. * @uattr: structure containing the extended parameters. * @flags: for future extension. +* +* long-desc: Sets the scheduling policy and attributes for a process, +* supporting multiple scheduling classes including real-time, +* deadline, and normal policies. Performs capability checks, +* validates parameters, enforces resource limits, and ensures +* bandwidth constraints for deadline tasks. +* context-flags: KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE +* +* param-count: 3 +* +* param: pid +* type: KAPI_TYPE_INT +* flags: KAPI_PARAM_IN +* constraint-type: KAPI_CONSTRAINT_RANGE +* range: 0, INT_MAX +* constraint: Must be >= 0, where 0 means current process +* +* param: uattr +* type: KAPI_TYPE_USER_PTR +* flags: KAPI_PARAM_IN | KAPI_PARAM_USER +* constraint-type: KAPI_CONSTRAINT_CUSTOM +* constraint: Valid user pointer to struct sched_attr +* +* struct: struct sched_attr +* size: 120 +* alignment: 8 +* field: size +* type: __u32 +* desc: Structure size for version compatibility +* constraint-type: KAPI_CONSTRAINT_RANGE +* range: 48, 512 +* constraint: Must be at least SCHED_ATTR_SIZE_VER0 +* field: sched_policy +* type: __u32 +* desc: Scheduling policy selector +* constraint-type: KAPI_CONSTRAINT_ENUM +* enum: SCHED_NORMAL(0), SCHED_FIFO(1), SCHED_RR(2), SCHED_BATCH(3), SCHED_IDLE(5), SCHED_DEADLINE(6), SCHED_EXT(7) +* field: sched_flags +* type: __u64 +* desc: Policy modifier flags +* constraint-type: KAPI_CONSTRAINT_MASK +* mask: SCHED_FLAG_ALL +* field: sched_nice +* type: __s32 +* desc: Nice value for CFS policies +* constraint-type: KAPI_CONSTRAINT_RANGE +* range: -20, 19 +* constraint: Only used for SCHED_NORMAL, SCHED_BATCH, SCHED_IDLE +* field: sched_priority +* type: __u32 +* desc: Priority for RT policies +* constraint-type: KAPI_CONSTRAINT_RANGE +* range: 1, 99 +* constraint: Only used for SCHED_FIFO, SCHED_RR +* field: sched_runtime +* type: __u64 +* desc: Runtime budget in nanoseconds +* constraint: Only used for SCHED_DEADLINE +* field: sched_deadline +* type: __u64 +* desc: Deadline in nanoseconds +* constraint: Only used for SCHED_DEADLINE +* field: sched_period +* type: __u64 +* desc: Period in nanoseconds (0 = use deadline) +* constraint: Only used for SCHED_DEADLINE +* field: sched_util_min +* type: __u32 +* desc: Minimum utilization hint (v1+) +* constraint-type: KAPI_CONSTRAINT_RANGE +* range: 0, 1024 +* constraint: Requires struct version >= 1 and SCHED_FLAG_UTIL_CLAMP_MIN +* field: sched_util_max +* type: __u32 +* desc: Maximum utilization hint (v1+) +* constraint-type: KAPI_CONSTRAINT_RANGE +* range: 0, 1024 +* constraint: Requires struct version >= 1 and SCHED_FLAG_UTIL_CLAMP_MAX +* +* param: flags +* type: KAPI_TYPE_UINT +* flags: KAPI_PARAM_IN +* range: 0, 0 +* constraint: Must be 0 (reserved for future use) +* +* validation-group: RT Policies +* policy: SCHED_FIFO, SCHED_RR +* rule: sched_priority must be in [1,99] +* rule: sched_nice must be 0 +* rule: No deadline parameters +* +* validation-group: CFS Policies +* policy: SCHED_NORMAL, SCHED_BATCH, SCHED_IDLE +* rule: sched_priority must be 0 +* rule: sched_nice must be in [-20,19] +* rule: No deadline parameters +* +* validation-group: Deadline Policy +* policy: SCHED_DEADLINE +* rule: sched_runtime > 0 +* rule: sched_deadline >= sched_runtime +* rule: sched_period == 0 || sched_period >= sched_deadline +* rule: sched_priority must be 0 +* rule: sched_nice must be 0 +* +* validation-group: Utilization Clamping +* flag: SCHED_FLAG_UTIL_CLAMP_MIN, SCHED_FLAG_UTIL_CLAMP_MAX +* rule: Requires struct version >= 1 (size >= 56) +* rule: util values must be in [0,1024] +* rule: util_min <= util_max +* +* return: +* type: KAPI_TYPE_INT +* check-type: KAPI_RETURN_ERROR_CHECK +* success: 0 +* +* error: EINVAL, Invalid parameters +* desc: Returned when uattr is NULL, pid < 0, flags != 0, +* attr.size < SCHED_ATTR_SIZE_VER0, invalid scheduling policy, +* invalid priority for policy, invalid sched_flags, or malformed +* sched_attr structure (e.g., DL runtime > deadline) +* +* error: ESRCH, Process not found +* desc: Returned when the specified pid does not exist +* +* error: EPERM, Insufficient privileges +* desc: Returned when lacking CAP_SYS_NICE for privileged operations, +* trying to change another user's process without CAP_SYS_NICE, +* or resetting SCHED_RESET_ON_FORK flag without privileges +* +* error: E2BIG, Structure size mismatch +* desc: Returned when sched_attr size is larger than kernel expects +* +* error: EFAULT, Bad user pointer +* desc: Returned when copying from user space fails or uattr is not +* a valid readable user pointer +* +* error: EBUSY, Bandwidth exceeded +* desc: Returned when SCHED_DEADLINE bandwidth would be exceeded or +* deadline admission test fails +* +* error: EAGAIN, Transient failure +* desc: Returned when unable to change cpus_allowed due to transient +* cpuset or CPU hotplug conditions +* +* error: ENOMEM, Memory allocation failed +* desc: Returned when unable to allocate memory for CPU masks +* +* error: EOPNOTSUPP, Feature not supported +* desc: Returned when utilization clamping is requested but +* CONFIG_UCLAMP_TASK is not enabled +* +* since-version: 3.14 +* +* lock: rq->lock +* type: KAPI_LOCK_SPINLOCK +* acquired: true +* released: true +* desc: Process runqueue lock for scheduler state changes +* +* lock: p->pi_lock +* type: KAPI_LOCK_SPINLOCK +* acquired: true +* released: true +* desc: Priority inheritance lock for PI chain adjustments +* +* lock: cpuset_mutex +* type: KAPI_LOCK_MUTEX +* acquired: true +* released: true +* desc: Cpuset mutex for SCHED_DEADLINE bandwidth checks +* +* +* signal: SIGXCPU +* direction: KAPI_SIGNAL_SEND +* action: KAPI_SIGNAL_ACTION_DEFAULT +* condition: SCHED_FLAG_DL_OVERRUN is set and deadline is missed +* desc: Sent to task when it exceeds its SCHED_DEADLINE runtime. +* The signal is sent asynchronously from the scheduler tick or +* deadline timer. Unlike other scheduling policies, SCHED_DEADLINE +* can generate SIGXCPU for runtime overruns rather than just +* CPU time limit violations. +* timing: KAPI_SIGNAL_TIME_DURING +* priority: 0 +* interruptible: no +* state-req: KAPI_SIGNAL_STATE_RUNNING +* +* examples: sched_setattr(0, &attr, 0); // Set attributes for current task +* sched_setattr(pid, &attr, 0); // Set attributes for specific task +* +* notes: The sched_attr structure supports forward/backward compatibility +* through its size field. Older kernels ignore newer fields. The syscall +* validates all parameters based on the scheduling policy. For SCHED_DEADLINE, +* it performs CBS (Constant Bandwidth Server) admission control. Priority +* changes may trigger immediate reschedule. RT policies require sched_priority +* in range [1,99]. Normal policies use nice values [-20,19] mapped to +* static_prio. Changes are atomic - either all succeed or none are applied. +* +* side-effect: KAPI_EFFECT_MODIFY_STATE | KAPI_EFFECT_PROCESS_STATE +* target: task scheduling attributes +* desc: Updates policy/priority/deadline parameters atomically +* reversible: yes +* +* +* side-effect: KAPI_EFFECT_MODIFY_STATE | KAPI_EFFECT_SCHEDULE +* target: runqueue +* desc: May requeue task with new priority and trigger reschedule +* condition: Task is runnable +* +* +* side-effect: KAPI_EFFECT_MODIFY_STATE +* target: deadline bandwidth +* desc: Allocates CBS bandwidth for SCHED_DEADLINE tasks +* condition: Policy is SCHED_DEADLINE +* reversible: yes +* +* +* side-effect: KAPI_EFFECT_MODIFY_STATE +* target: timer slack +* desc: Sets timer slack to 0 for RT/DL policies +* condition: RT or DEADLINE policy +* +* +* side-effect: KAPI_EFFECT_MODIFY_STATE +* target: PI chain +* desc: Updates priority inheritance chain if task has PI waiters +* condition: Task has PI waiters +* +* +* side-effect: KAPI_EFFECT_MODIFY_STATE | KAPI_EFFECT_SCHEDULE +* target: CPU +* desc: May migrate task to different CPU based on affinity/bandwidth +* condition: SCHED_DEADLINE or cpuset changes +* +* +* state-trans: task->policy +* from: any policy +* to: new policy +* desc: Task scheduling policy changes per sched_attr +* +* +* state-trans: task->rt_priority +* from: any +* to: 0-99 or 0 +* desc: RT priority updated for RT policies, 0 for others +* +* +* state-trans: task->normal_prio +* from: any +* to: recalculated +* desc: Normal priority recalculated based on policy/nice +* +* +* state-trans: task->sched_reset_on_fork +* from: 0/1 +* to: 0/1 +* desc: Reset-on-fork flag updated per SCHED_FLAG_RESET_ON_FORK +* +* +* state-trans: task->dl +* from: inactive/active +* to: active/inactive +* desc: Deadline entity activated for SCHED_DEADLINE +* +* +* capability: CAP_SYS_NICE +* type: KAPI_CAP_BYPASS_CHECK +* desc: CAP_SYS_NICE capability +* allows: Set RT/DL policies, increase priority, nice < 0, change other users' tasks, remove SCHED_FLAG_RESET_ON_FORK +* without: Can only set SCHED_NORMAL/BATCH/IDLE, decrease priority, nice >= 0, modify own tasks +* condition: Checked when setting RT/DL policy, decreasing nice, or modifying other user's tasks +* priority: 0 +* +* +* constraint: Valid Scheduling Policy +* desc: The sched_policy field must be one of: SCHED_NORMAL (0), SCHED_FIFO (1), SCHED_RR (2), +* SCHED_BATCH (3), SCHED_IDLE (5), SCHED_DEADLINE (6), or SCHED_EXT (7) if configured. +* Invalid policies result in -EINVAL. +* expr: uattr->sched_policy >= 0 && (uattr->sched_policy <= SCHED_DEADLINE || (uattr->sched_policy == SCHED_EXT && IS_ENABLED(CONFIG_SCHED_CLASS_EXT))) +* +* +* constraint: RT Priority Range +* desc: For SCHED_FIFO and SCHED_RR policies, sched_priority must be in range [1, 99] +* where 1 is lowest and 99 is highest RT priority. For other policies, sched_priority must be 0. +* expr: rt_policy(uattr->sched_policy) ? (uattr->sched_priority >= 1 && uattr->sched_priority <= 99) : (uattr->sched_priority == 0) +* +* +* constraint: Nice Value Range +* desc: For SCHED_NORMAL, SCHED_BATCH, and SCHED_IDLE policies, the nice value must be in range [-20, 19] +* where -20 is highest priority (least nice) and 19 is lowest priority (most nice). +* expr: fair_policy(uattr->sched_policy) ? (uattr->sched_nice >= MIN_NICE && uattr->sched_nice <= MAX_NICE) : 1 +* +* +* constraint: SCHED_DEADLINE CBS Rules +* desc: For SCHED_DEADLINE, must satisfy: sched_runtime > 0, sched_deadline >= sched_runtime, +* sched_period >= sched_deadline. If period is 0, it defaults to deadline. +* expr: dl_policy(uattr->sched_policy) ? (uattr->sched_runtime > 0 && uattr->sched_runtime <= uattr->sched_deadline && (uattr->sched_period == 0 || uattr->sched_period >= uattr->sched_deadline)) : 1 +* +* +* constraint: Utilization Clamping Range +* desc: If sched_flags includes SCHED_FLAG_UTIL_CLAMP_MIN/MAX, the util_min and util_max values +* must be in range [0, 1024] where 1024 represents 100% utilization. +* expr: (uattr->sched_flags & SCHED_FLAG_UTIL_CLAMP) ? (uattr->sched_util_min >= 0 && uattr->sched_util_min <= SCHED_CAPACITY_SCALE && uattr->sched_util_max >= 0 && uattr->sched_util_max <= SCHED_CAPACITY_SCALE && uattr->sched_util_min <= uattr->sched_util_max) : 1 +* +* +* constraint: SCHED_DEADLINE Bandwidth +* desc: The sum of runtime/period ratios for all SCHED_DEADLINE tasks on the system +* must not exceed the available CPU capacity. This global bandwidth check prevents system overload. +* +* +* constraint: Structure Size Compatibility +* desc: The attr.size field must be at least SCHED_ATTR_SIZE_VER0 (48 bytes) and no larger than +* the kernel's known structure size to ensure forward/backward compatibility. */ SYSCALL_DEFINE3(sched_setattr, pid_t, pid, struct sched_attr __user *, uattr, unsigned int, flags)
Signature · 1 line
2.50.1
RFC PATCH v4 5/7 mm/mlock: add API specification for mlock
In reply to Sasha LevinAdd kernel API specification for the mlock() system call.
--- mm/mlock.c | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+)
mm/mlock.c +134 -0
@@ -656,6 +656,140 @@ static __must_check int do_mlock(unsigned long start, size_t len, vm_flags_t flareturn 0 ; } +/** +* sys_mlock - Lock pages in memory +* @start: Starting address of memory range to lock +* @len: Length of memory range to lock in bytes +* +* long-desc: Locks pages in the specified address range into RAM, preventing +* them from being paged to swap. Requires CAP_IPC_LOCK capability +* or RLIMIT_MEMLOCK resource limit. +* +* context-flags: KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE +* +* param: start, KAPI_TYPE_UINT +* flags: KAPI_PARAM_IN +* constraint-type: KAPI_CONSTRAINT_NONE +* constraint: Automatically page-aligned down by kernel (PAGE_ALIGN_DOWN) +* +* param: len, KAPI_TYPE_UINT +* flags: KAPI_PARAM_IN +* constraint-type: KAPI_CONSTRAINT_RANGE +* range: 0, LONG_MAX +* constraint: Automatically page-aligned up by kernel (PAGE_ALIGN) +* +* return: +* type: KAPI_TYPE_INT +* check-type: KAPI_RETURN_ERROR_CHECK +* success: 0 +* +* error: ENOMEM, Address range issue +* desc: Some of the specified range is not mapped, has unmapped gaps, +* or the lock would cause the number of mapped regions to exceed the limit. +* +* error: EPERM, Insufficient privileges +* desc: The caller is not privileged (no CAP_IPC_LOCK) and RLIMIT_MEMLOCK is 0. +* +* error: EINVAL, Address overflow +* desc: The result of the addition start+len was less than start (arithmetic overflow). +* +* error: EAGAIN, Some or all memory could not be locked +* desc: Some or all of the specified address range could not be locked. +* +* error: EINTR, Interrupted by signal +* desc: The operation was interrupted by a fatal signal before completion. +* +* error: EFAULT, Bad address +* desc: The specified address range contains invalid addresses that cannot be accessed. +* +* since-version: 2.0 +* +* lock: mmap_lock, KAPI_LOCK_RWLOCK +* acquired: true +* released: true +* desc: Process memory map write lock +* +* signal: FATAL +* direction: KAPI_SIGNAL_RECEIVE +* action: KAPI_SIGNAL_ACTION_RETURN +* condition: Fatal signal pending +* desc: Fatal signals (SIGKILL) can interrupt the operation at two points: +* when acquiring mmap_write_lock_killable() and during page population +* in __mm_populate(). Returns -EINTR. Non-fatal signals do NOT interrupt +* mlock - the operation continues even if SIGINT/SIGTERM are received. +* error: -EINTR +* timing: KAPI_SIGNAL_TIME_DURING +* priority: 0 +* interruptible: yes +* state-req: KAPI_SIGNAL_STATE_RUNNING +* +* examples: mlock(addr, 4096); // Lock one page +* mlock(addr, len); // Lock range of pages +* +* notes: Memory locks do not stack - multiple calls on the same range can be +* undone by a single munlock. Locks are not inherited by child processes. +* Pages are locked on whole page boundaries. Commonly used by real-time +* applications to prevent page faults during time-critical operations. +* Also used for security to prevent sensitive data (e.g., cryptographic keys) +* from being written to swap. Note: locked pages may still be saved to +* swap during system suspend/hibernate. +* +* Tagged addresses are automatically handled via untagged_addr(). The operation +* occurs in two phases: first VMAs are marked with VM_LOCKED, then pages are +* populated into memory. When checking RLIMIT_MEMLOCK, the kernel optimizes +* by recounting locked memory to avoid double-counting overlapping regions. +* side-effect: KAPI_EFFECT_MODIFY_STATE | KAPI_EFFECT_ALLOC_MEMORY +* target: process memory +* desc: Locks pages into physical memory, preventing swapping +* reversible: yes +* +* side-effect: KAPI_EFFECT_MODIFY_STATE +* target: mm->locked_vm +* desc: Increases process locked memory counter +* reversible: yes +* +* side-effect: KAPI_EFFECT_ALLOC_MEMORY +* target: physical pages +* desc: May allocate and populate page table entries +* condition: Pages not already present +* reversible: yes +* +* side-effect: KAPI_EFFECT_MODIFY_STATE | KAPI_EFFECT_ALLOC_MEMORY +* target: page faults +* desc: Triggers page faults to bring pages into memory +* condition: Pages not already resident +* +* side-effect: KAPI_EFFECT_MODIFY_STATE +* target: VMA splitting +* desc: May split existing VMAs at lock boundaries +* condition: Lock range partially overlaps existing VMA +* +* state-trans: memory pages +* from: swappable +* to: locked in RAM +* desc: Pages become non-swappable and pinned in physical memory +* +* state-trans: VMA flags +* from: unlocked +* to: VM_LOCKED set +* desc: Virtual memory area marked as locked +* +* capability: CAP_IPC_LOCK, KAPI_CAP_BYPASS_CHECK, CAP_IPC_LOCK capability +* allows: Lock unlimited amount of memory (no RLIMIT_MEMLOCK enforcement) +* without: Must respect RLIMIT_MEMLOCK resource limit +* condition: Checked when RLIMIT_MEMLOCK is 0 or locking would exceed limit +* priority: 0 +* +* constraint: RLIMIT_MEMLOCK Resource Limit +* desc: The RLIMIT_MEMLOCK soft resource limit specifies the maximum bytes of memory that may be locked into RAM. Unprivileged processes are restricted to this limit. CAP_IPC_LOCK capability allows bypassing this limit entirely. The limit is enforced per-process, not per-user. +* expr: locked_memory + request_size <= RLIMIT_MEMLOCK || CAP_IPC_LOCK +* +* constraint: Memory Pressure and OOM +* desc: Locking large amounts of memory can cause system-wide memory pressure and potentially trigger the OOM killer. The kernel does not prevent locking memory that would destabilize the system. +* +* constraint: Special Memory Areas +* desc: Some memory types cannot be locked or are silently skipped: VM_IO/VM_PFNMAP areas (device mappings) are skipped; Hugetlb pages are inherently pinned and skipped; DAX mappings are always present in memory and skipped; Secret memory (memfd_secret) mappings are skipped; VM_DROPPABLE memory cannot be locked and is skipped; Gate VMA (kernel entry point) is skipped; VM_LOCKED areas are already locked. These special areas are silently excluded without error. +*/ SYSCALL_DEFINE2(mlock, unsigned long, start, size_t, len) {return do_mlock (start, len,VM_LOCKED );
Signature · 1 line
2.50.1
RFC PATCH v4 6/7 fs/exec: add API specification for execveat
In reply to Sasha LevinAdd kernel API specification for the execveat() system call.
--- fs/exec.c | 594 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 594 insertions(+)
fs/exec.c +594 -0
@@ -2010,6 +2010,600 @@ SYSCALL_DEFINE3(execve,return do_execve (getname (filename), argv, envp); } +/** +* sys_execveat - Execute program relative to directory file descriptor +* @fd: File descriptor of directory for relative pathname +* @filename: Pathname of program to execute +* @argv: Argument vector for new program +* @envp: Environment vector for new program +* @flags: Execution flags +* +* long-desc: Executes a new program, replacing the current process image with a new +* process image. Similar to execve(), but the program is specified via a +* directory file descriptor and pathname. Supports execution of scripts, +* ELF binaries, and other registered binary formats. Handles setuid/setgid +* executables with appropriate privilege transitions. The execveat() system +* call combines and extends the functionality of execve() and fexecve(). +* context-flags: KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE +* +* param: fd +* type: KAPI_TYPE_INT +* flags: KAPI_PARAM_IN +* constraint-type: KAPI_CONSTRAINT_CUSTOM +* constraint: Valid file descriptor or AT_FDCWD (-100) for current directory +* +* param: filename +* type: KAPI_TYPE_USER_PTR +* flags: KAPI_PARAM_IN | KAPI_PARAM_USER +* constraint-type: KAPI_CONSTRAINT_CUSTOM +* constraint: Can be relative (to fd), absolute, or empty if AT_EMPTY_PATH is set +* +* param: argv +* type: KAPI_TYPE_USER_PTR +* flags: KAPI_PARAM_IN | KAPI_PARAM_USER +* constraint-type: KAPI_CONSTRAINT_CUSTOM +* constraint: NULL-terminated array of strings, total size < MAX_ARG_STRLEN * MAX_ARG_STRINGS +* +* param: envp +* type: KAPI_TYPE_USER_PTR +* flags: KAPI_PARAM_IN | KAPI_PARAM_USER +* constraint-type: KAPI_CONSTRAINT_CUSTOM +* constraint: NULL-terminated array of strings, total size < MAX_ARG_STRLEN * MAX_ARG_STRINGS +* +* param: flags +* type: KAPI_TYPE_INT +* flags: KAPI_PARAM_IN +* constraint-type: KAPI_CONSTRAINT_BITMASK +* valid-mask: AT_EMPTY_PATH | AT_SYMLINK_NOFOLLOW | AT_EXECVE_CHECK +* constraint: AT_* flag validation +* constraint: AT_EMPTY_PATH allows empty filename +* constraint: AT_SYMLINK_NOFOLLOW prevents following symlinks +* constraint: AT_EXECVE_CHECK only checks if execution would succeed +* +* return: +* type: KAPI_TYPE_INT +* check-type: KAPI_RETURN_NO_RETURN +* success: 0 +* desc: On success, execveat() does not return (except with AT_EXECVE_CHECK which returns 0). On error, -1 is returned and errno is set +* +* error: E2BIG, Argument list too long +* desc: Total size of argument and environment strings exceeds MAX_ARG_STRLEN * MAX_ARG_STRINGS +* or a single string exceeds MAX_ARG_STRLEN, or too many arguments (> MAX_ARG_STRINGS) +* +* error: EACCES, Permission denied +* desc: Execute permission denied on file, or search permission denied on path component +* or file is not regular file, or filesystem mounted noexec +* or file on read-only filesystem and requires writing +* +* error: EAGAIN, Resource limit exceeded +* desc: RLIMIT_NPROC resource limit exceeded and process lacks CAP_SYS_ADMIN and CAP_SYS_RESOURCE +* or cannot allocate necessary kernel structures due to memory pressure +* +* error: EBADF, Bad file descriptor +* desc: The fd argument is not a valid file descriptor, or is not open +* or filename is empty and AT_EMPTY_PATH not specified +* +* error: EFAULT, Bad address +* desc: filename, argv, or envp points outside accessible address space +* or argv/envp element points to invalid memory +* +* error: EINTR, Interrupted by signal +* desc: A signal was caught during execution of execveat() +* typically during the security checks or while setting up the new program +* +* error: EINVAL, Invalid argument +* desc: Invalid flags specified, or ELF interpreter invalid +* or incompatible architecture, or fd refers to something that cannot be executed +* +* error: EIO, I/O error +* desc: An I/O error occurred while reading from the file system +* +* error: EISDIR, Is a directory +* desc: The final component of filename or the file referred to by fd is a directory +* or an ELF interpreter was a directory +* +* error: ELIBBAD, Invalid ELF interpreter +* desc: An ELF interpreter was not in a recognized format +* +* error: ELOOP, Too many symbolic links +* desc: Too many symbolic links encountered in resolving filename or fd +* or maximum recursion depth exceeded in script interpreter resolution +* +* error: EMFILE, Too many open files +* desc: The per-process limit on open file descriptors has been reached +* +* error: ENAMETOOLONG, Filename too long +* desc: filename is too long, or a component of the pathname exceeds NAME_MAX +* or pathname exceeds PATH_MAX +* +* error: ENFILE, System file table overflow +* desc: The system-wide limit on the total number of open files has been reached +* +* error: ENOENT, No such file or directory +* desc: filename or a component of the path does not exist +* or the file referred to by fd does not exist (when AT_EMPTY_PATH) +* or interpreter does not exist +* +* error: ENOEXEC, Exec format error +* desc: The file is not in a recognized executable format, is for wrong architecture +* or has some other format error that prevents execution +* +* error: ENOMEM, Out of memory +* desc: Insufficient kernel memory available to execute the new program +* cannot allocate page tables, or other memory structures +* +* error: ENOTDIR, Not a directory +* desc: A component of the path prefix of filename or fd is not a directory +* +* error: EPERM, Operation not permitted +* desc: The filesystem is mounted nosuid, the user is not root, and the file has +* set-user-ID or set-group-ID bit set, or file is on a filesystem mounted +* with MS_NOEXEC, or the process is being traced +* +* error: ETXTBSY, Text file busy +* desc: The executable was open for writing by one or more processes +* +* +* lock: cred_guard_mutex +* type: KAPI_LOCK_MUTEX +* acquired: true +* released: true +* desc: Process credential guard mutex - prevents concurrent credential changes during exec +* +* lock: exec_update_lock +* type: KAPI_LOCK_RWLOCK +* acquired: true +* released: true +* desc: Signal exec update lock - taken for write during exec to prevent racing changes +* +* lock: sighand->siglock +* type: KAPI_LOCK_SPINLOCK +* acquired: true +* released: true +* desc: Signal handler spinlock - protects signal handler updates during exec +* +* lock: tasklist_lock +* type: KAPI_LOCK_RWLOCK +* acquired: true +* released: true +* desc: Global task list lock - taken for write when updating thread group during exec +* +* lock: binfmt_lock +* type: KAPI_LOCK_RWLOCK +* acquired: true +* released: true +* desc: Binary format list lock - taken for read when searching for binary handlers +* +* lock: mmap_lock +* type: KAPI_LOCK_RWLOCK +* acquired: true +* released: true +* desc: Memory map lock - taken when setting up new memory layout for executed program +* +* signal: SIGKILL +* direction: KAPI_SIGNAL_RECEIVE +* action: KAPI_SIGNAL_ACTION_TERMINATE +* condition: Process killed during exec +* desc: If the process is killed (SIGKILL) during execution, the exec +* operation is aborted. This can happen at various points including +* credential changes, memory setup, or binary loading. The process +* terminates immediately without returning from execveat(). +* timing: KAPI_SIGNAL_TIME_DURING +* priority: 0 +* restartable: no +* state-req: KAPI_SIGNAL_STATE_RUNNING +* +* signal: FATAL +* direction: KAPI_SIGNAL_RECEIVE +* action: KAPI_SIGNAL_ACTION_RETURN +* condition: Fatal signal pending +* desc: Fatal signals interrupt execveat at specific checkpoints: +* during argument copying, credential setup, and binary loading. +* Returns -EINTR or -ERESTARTNOINTR. After point of no return, +* signals cause the process to terminate rather than return. +* error: -EINTR +* timing: KAPI_SIGNAL_TIME_BEFORE +* priority: 1 +* interruptible: yes +* state-req: KAPI_SIGNAL_STATE_RUNNING +* +* signal: SIGKILL_THREADS +* direction: KAPI_SIGNAL_SEND +* action: KAPI_SIGNAL_ACTION_TERMINATE +* condition: Multi-threaded process doing exec +* desc: During de_thread(), zap_other_threads() sends SIGKILL to all +* other threads in the thread group to ensure only the execing thread +* survives. This ensures the process becomes single-threaded. +* target: All other threads in thread group +* timing: KAPI_SIGNAL_TIME_DURING +* priority: 0 +* +* signal: HANDLERS_RESET +* direction: KAPI_SIGNAL_HANDLE +* action: KAPI_SIGNAL_ACTION_CUSTOM +* condition: Signal has a handler installed +* desc: flush_signal_handlers() resets all signal handlers to SIG_DFL +* except for signals that are ignored (SIG_IGN). This happens after +* de_thread() completes to give the new program a clean signal state. +* timing: KAPI_SIGNAL_TIME_DURING +* +* +* signal: IGNORED_PRESERVED +* direction: KAPI_SIGNAL_IGNORE +* action: KAPI_SIGNAL_ACTION_CUSTOM +* condition: Signal disposition is SIG_IGN +* desc: Signals set to SIG_IGN are preserved across exec. This is +* POSIX-compliant behavior allowing parent processes to control +* signal handling in children. +* timing: KAPI_SIGNAL_TIME_DURING +* +* +* signal: PENDING_CLEARED +* direction: KAPI_SIGNAL_HANDLE +* action: KAPI_SIGNAL_ACTION_CUSTOM +* condition: Any pending signals +* desc: All pending signals are cleared during exec. This includes +* both thread-specific and process-wide pending signals to prevent +* unexpected signal delivery to the new program. +* timing: KAPI_SIGNAL_TIME_DURING +* +* +* signal: TIMER_SIGNALS +* direction: KAPI_SIGNAL_HANDLE +* action: KAPI_SIGNAL_ACTION_CUSTOM +* condition: Timer-generated signals pending +* desc: flush_itimer_signals() clears any pending timer signals +* (SIGALRM, SIGVTALRM, SIGPROF) to prevent confusion in the new program. +* Timer settings are also reset. +* timing: KAPI_SIGNAL_TIME_DURING +* +* +* signal: SIGCHLD_SETUP +* direction: KAPI_SIGNAL_SEND +* action: KAPI_SIGNAL_ACTION_DEFAULT +* condition: Process exit after exec +* desc: The exit_signal is set to SIGCHLD during exec, ensuring the +* parent will receive SIGCHLD when this process terminates. +* target: Parent process +* timing: KAPI_SIGNAL_TIME_AFTER +* +* +* signal: SIGALTSTACK_CLEARED +* direction: KAPI_SIGNAL_HANDLE +* action: KAPI_SIGNAL_ACTION_CUSTOM +* condition: Process had alternate signal stack +* desc: Any alternate signal stack (sigaltstack) is not preserved +* across exec. The new program starts with no alternate stack. +* timing: KAPI_SIGNAL_TIME_DURING +* +* +* signal: SIGSEGV_FORCED +* direction: KAPI_SIGNAL_SEND +* action: KAPI_SIGNAL_ACTION_TERMINATE +* condition: Error after point of no return +* desc: If an error occurs after the point of no return and no fatal +* signal is already pending, force_fatal_sig(SIGSEGV) is called to +* terminate the process since it cannot return to the old state. +* target: Current process +* timing: KAPI_SIGNAL_TIME_AFTER +* priority: 0 +* +* side-effect: KAPI_EFFECT_PROCESS_STATE | KAPI_EFFECT_IRREVERSIBLE +* target: process image +* desc: Completely replaces the process image with new program. +* The entire process address space, including code, data, heap, +* and stack are replaced. Only PID, parent PID, and some signal +* dispositions are preserved. This is irreversible once past the +* point of no return. +* +* +* side-effect: KAPI_EFFECT_MODIFY_STATE | KAPI_EFFECT_CREDS +* target: process credentials +* desc: Updates process credentials for setuid/setgid executables. +* Effective UID/GID are changed to file owner/group if setuid/setgid +* bits are set and filesystem allows. Real UID/GID unchanged unless +* explicitly set. Saved set-user-ID updated. Capabilities may be +* gained or lost. AT_SECURE is set for security transitions. +* condition: File has setuid or setgid bits +* reversible: no +* +* +* side-effect: KAPI_EFFECT_CLOSE_FD +* target: file descriptors +* desc: Closes file descriptors marked with FD_CLOEXEC. +* All file descriptors with FD_CLOEXEC flag are automatically closed. +* Other file descriptors remain open and available to new program. +* Standard streams (0,1,2) typically preserved unless explicitly marked. +* reversible: no +* +* +* side-effect: KAPI_EFFECT_SIGNAL_STATE +* target: signal handlers +* desc: Resets signal handlers to default. +* All caught signals are reset to default disposition (SIG_DFL). +* Ignored signals (SIG_IGN) remain ignored except in special cases. +* Signal mask is preserved. Pending signals are preserved unless +* they would be ignored by the new program. +* reversible: no +* +* +* side-effect: KAPI_EFFECT_MEMORY_MAP +* target: memory mappings +* desc: Destroys all existing memory mappings. +* All memory mappings including shared memory, mmapped files, and +* anonymous mappings are unmapped. New mappings are created for +* the executed program's code, data, and stack. Shared memory +* attachments are detached. +* reversible: no +* +* +* side-effect: KAPI_EFFECT_THREAD_STATE +* target: thread group +* desc: Terminates all other threads in thread group. +* If the calling thread is part of a multi-threaded process, +* all other threads are terminated. The thread group becomes +* single-threaded with only the execing thread surviving. +* Thread group leader transfers if necessary. +* condition: Multi-threaded process +* reversible: no +* +* +* side-effect: KAPI_EFFECT_RLIMIT +* target: resource limits +* desc: Preserves most resource limits. +* Resource limits (RLIMIT_*) are generally preserved across exec. +* RLIMIT_CPU timer is reset. RLIMIT_STACK may be adjusted for +* the new program's requirements. +* +* +* side-effect: KAPI_EFFECT_FILESYSTEM +* target: working directory +* desc: Preserves working directory and root. +* Current working directory and root directory are preserved. +* Umask is preserved. Close-on-exec file descriptors are closed. +* File locks are preserved if not associated with closed descriptors. +* +* +* side-effect: KAPI_EFFECT_ACCOUNTING +* target: process accounting +* desc: Updates accounting information. +* Process accounting records exec event. CPU timers reset. +* Start time updated. Command name (comm) changed to new program. +* Audit events generated for security-relevant transitions. +* +* +* side-effect: KAPI_EFFECT_NAMESPACE +* target: personality +* desc: May change execution personality. +* Execution personality (e.g., Linux, SVR4, etc.) may change based +* on binary format. This affects system call behavior, signal +* numbering, and other ABI details. Usually preserved but can +* change for compatibility. +* condition: Binary requires different personality +* +* +* side-effect: KAPI_EFFECT_IO_CANCEL +* target: io_uring +* desc: Cancels all io_uring operations. +* io_uring_task_cancel() is called to cancel any pending +* io_uring operations. This prevents the new program from inheriting +* incomplete asynchronous I/O operations from the old program. +* +* +* side-effect: KAPI_EFFECT_FILES_UNSHARE +* target: file table +* desc: Unshares file descriptor table. +* unshare_files() ensures the process has its own file +* descriptor table, not shared with other processes. This is required +* for security during credential changes. +* +* +* side-effect: KAPI_EFFECT_PTRACE +* target: ptrace event +* desc: Generates PTRACE_EVENT_EXEC. +* ptrace_event(PTRACE_EVENT_EXEC) notifies any process +* tracing this one that an exec has occurred. The tracer can then +* update its state and continue tracing the new program. +* +* +* side-effect: KAPI_EFFECT_CONNECTOR +* target: process connector +* desc: Sends exec notification. +* proc_exec_connector() sends a notification through +* the process connector (cn_proc) subsystem to inform interested +* listeners that an exec has occurred. +* +* +* side-effect: KAPI_EFFECT_SCHEDULER +* target: scheduler state +* desc: Updates scheduler state for exec. +* sched_exec() performs scheduler operations for exec, +* potentially migrating the task to a less loaded CPU. Also manages +* MM context IDs via sched_mm_cid_before_execve/after_execve. +* +* +* side-effect: KAPI_EFFECT_RSEQ +* target: restartable sequences +* desc: Handles rseq for exec. +* rseq_execve() handles restartable sequence +* state during exec. The rseq area is cleared to prevent the new +* program from using stale rseq data from the old program. +* +* +* side-effect: KAPI_EFFECT_USER_EVENTS +* target: user events +* desc: Notifies user event subsystem. +* user_events_execve() notifies the user events +* tracing subsystem that an exec has occurred, allowing userspace +* tracing tools to track process transitions. +* +* +* side-effect: KAPI_EFFECT_NUMA +* target: NUMA state +* desc: Cleans up NUMA task state. +* task_numa_free() releases NUMA-related task state +* including fault statistics and placement information. The new +* program starts with fresh NUMA placement decisions. +* +* +* state-trans: executing +* to: new program +* condition: exec succeeds +* target: process image +* desc: Process transitions from executing current program to executing new program +* +* +* state-trans: multi-threaded +* to: single-threaded +* condition: exec in threaded process +* target: thread group +* desc: Multi-threaded process becomes single-threaded as all other threads terminate +* +* +* state-trans: unprivileged +* to: privileged +* condition: setuid/setgid exec +* target: process credentials +* desc: Process may gain privileges through setuid/setgid execution +* +* +* state-trans: privileged +* to: unprivileged +* condition: capability drop +* target: process capabilities +* desc: Process may lose capabilities when executing non-privileged binary +* +* +* state-trans: dumpable +* to: non-dumpable +* condition: security transition +* target: process dumpability +* desc: Process becomes non-dumpable after setuid/setgid or capability changes +* +* +* capability: CAP_SYS_ADMIN +* type: KAPI_CAP_BYPASS +* desc: Allows exceeding RLIMIT_NPROC process limit +* allows: Allows exceeding RLIMIT_NPROC process limit +* without: Execution fails with EAGAIN if RLIMIT_NPROC exceeded +* condition: Process count at or above RLIMIT_NPROC +* priority: 0 +* +* +* capability: CAP_SYS_RESOURCE +* type: KAPI_CAP_BYPASS +* desc: Allows exceeding RLIMIT_NPROC process limit +* allows: Allows exceeding RLIMIT_NPROC process limit +* without: Execution fails with EAGAIN if RLIMIT_NPROC exceeded +* condition: Process count at or above RLIMIT_NPROC +* priority: 0 +* +* +* capability: CAP_DAC_OVERRIDE +* type: KAPI_CAP_BYPASS +* desc: Allows execution of files without execute permission +* allows: Allows execution of files without execute permission +* without: Must have execute permission on file +* condition: File lacks execute permission +* priority: 0 +* +* +* capability: CAP_MAC_ADMIN +* type: KAPI_CAP_BYPASS +* desc: May bypass MAC policy restrictions on execution +* allows: May bypass MAC policy restrictions on execution +* without: Subject to mandatory access control policies +* condition: MAC policy would deny execution +* priority: 0 +* +* +* constraint: Binary Format Support +* desc: The kernel must have support for the binary format being executed (ELF, script, etc). +* Binary format handlers are registered via register_binfmt(). +* If no handler recognizes the format, execution fails with ENOEXEC. +* expr: binfmt_handler_exists(file) +* +* constraint: Stack Size Limits +* desc: The combined size of arguments and environment cannot exceed the stack limit. +* The kernel enforces MAX_ARG_STRLEN (32 pages) per string and MAX_ARG_STRINGS total strings. +* Additionally respects RLIMIT_STACK. +* expr: total_size <= min(RLIMIT_STACK/4, MAX_ARG_STRLEN * MAX_ARG_STRINGS) +* +* +* constraint: Process Count Limit +* desc: If RLIMIT_NPROC is exceeded, execution fails with EAGAIN unless the process has +* CAP_SYS_ADMIN or CAP_SYS_RESOURCE capabilities. This prevents fork bombs and resource exhaustion. +* expr: user_processes < RLIMIT_NPROC || CAP_SYS_ADMIN || CAP_SYS_RESOURCE +* +* +* constraint: Setuid/Setgid Execution +* desc: Setuid/setgid bits are honored only if: filesystem is not mounted nosuid, +* file has appropriate bits set, and user namespace allows the mapping. +* AT_SECURE flag is set for security-sensitive transitions. +* expr: !nosuid_mount && (S_ISUID || S_ISGID) && uid_mappable && gid_mappable +* +* +* constraint: Script Interpreter Limits +* desc: Script execution (#! interpreter) has a maximum recursion depth of 4 levels +* to prevent infinite loops. The interpreter line is limited to BINPRM_BUF_SIZE (256) bytes. +* expr: interpreter_depth <= 4 && shebang_len <= BINPRM_BUF_SIZE +* +* +* constraint: Memory Layout Requirements +* desc: The new program requires sufficient virtual memory for code, data, stack, and heap. +* The kernel must be able to set up page tables and allocate initial pages. +* Fails with ENOMEM if insufficient. +* expr: available_memory >= program_requirements +* +* +* constraint: Security Module Checks +* desc: LSM (Linux Security Module) hooks are called at multiple points: +* security_bprm_check(), security_bprm_creds_from_file(), +* security_bprm_committing_creds(), security_bprm_committed_creds(). +* Any can deny execution. +* expr: all_lsm_checks_pass() +* +* +* constraint: File Descriptor Preservation +* desc: File descriptors marked FD_CLOEXEC are closed during exec. +* Others remain open in the new program. The AT_EMPTY_PATH flag requires +* the fd to refer to a regular file with execute permission. +* expr: fd_valid && (filename || AT_EMPTY_PATH) && (!FD_CLOEXEC || will_close) +* +* +* constraint: Point of No Return +* desc: Once the point of no return is reached (bprm->point_of_no_return set), +* the exec cannot fail gracefully. Any errors after this point result in +* process termination via force_fatal_sig(SIGSEGV) rather than returning an error to userspace. +* expr: !point_of_no_return || (error => process_terminated) +* +* examples: execveat(AT_FDCWD, "/bin/ls", argv, envp, 0); // Execute absolute path +* execveat(dirfd, "bin/ls", argv, envp, 0); // Execute relative to dirfd +* execveat(fd, "", argv, envp, AT_EMPTY_PATH); // Execute file referenced by fd +* execveat(dirfd, "script", argv, envp, AT_SYMLINK_NOFOLLOW); // Don't follow symlinks +* execveat(AT_FDCWD, "/bin/test", argv, envp, AT_EXECVE_CHECK); // Check if exec would succeed +* +* notes: execveat() is the most flexible exec variant, allowing execution relative to +* directory file descriptors and direct execution of already-open files. The +* AT_EMPTY_PATH flag enables fexecve()-like behavior. AT_EXECVE_CHECK (since +* Linux 6.12) only checks if execution would be allowed without actually executing, +* returning 0 on success. The function never returns on success (except with +* AT_EXECVE_CHECK) - the calling process image is completely replaced. Use fork() or +* clone() first if you want to preserve the parent process. +* +* Security considerations: Check-use race conditions are avoided when AT_EMPTY_PATH +* is used with a pre-opened file descriptor. Setuid/setgid bits may be ignored +* in various circumstances including nosuid mounts, user namespaces without +* mappings, and certain security policies. The dumpability of the process +* may change, affecting ptrace attachability and core dump generation. +* +* All threads except the calling thread are terminated. Signal handlers are +* reset but the signal mask is preserved. File descriptors are preserved +* except those marked FD_CLOEXEC. The point of no return is reached during +* binary loading - after this point, errors are fatal to the process. +* +* since-version: 3.19 +*/ SYSCALL_DEFINE5(execveat, int, fd, const char __user *, filename, const char __user *const __user *, argv,
Signature · 1 line
2.50.1
RFC PATCH v4 7/7 tools/kapi: Add kernel API specification extraction tool
In reply to Sasha LevinThe kapi tool extracts and displays kernel API specifications.
--- Documentation/admin-guide/kernel-api-spec.rst | 198 +++- tools/kapi/.gitignore | 4 + tools/kapi/Cargo.toml | 19 + tools/kapi/src/extractor/debugfs.rs | 442 +++++++++ tools/kapi/src/extractor/kerneldoc_parser.rs | 694 ++++++++++++++ tools/kapi/src/extractor/mod.rs | 461 +++++++++ tools/kapi/src/extractor/source_parser.rs | 213 +++++ .../src/extractor/vmlinux/binary_utils.rs | 180 ++++ .../src/extractor/vmlinux/magic_finder.rs | 102 ++ tools/kapi/src/extractor/vmlinux/mod.rs | 869 +++++++++++++++++ tools/kapi/src/formatter/json.rs | 468 +++++++++ tools/kapi/src/formatter/mod.rs | 145 +++ tools/kapi/src/formatter/plain.rs | 558 +++++++++++ tools/kapi/src/formatter/rst.rs | 621 ++++++++++++ tools/kapi/src/formatter/shall.rs | 891 ++++++++++++++++++ tools/kapi/src/main.rs | 116 +++ 16 files changed, 5978 insertions(+), 3 deletions(-) create mode 100644 tools/kapi/.gitignore create mode 100644 tools/kapi/Cargo.toml create mode 100644 tools/kapi/src/extractor/debugfs.rs create mode 100644 tools/kapi/src/extractor/kerneldoc_parser.rs create mode 100644 tools/kapi/src/extractor/mod.rs create mode 100644 tools/kapi/src/extractor/source_parser.rs create mode 100644 tools/kapi/src/extractor/vmlinux/binary_utils.rs create mode 100644 tools/kapi/src/extractor/vmlinux/magic_finder.rs create mode 100644 tools/kapi/src/extractor/vmlinux/mod.rs create mode 100644 tools/kapi/src/formatter/json.rs create mode 100644 tools/kapi/src/formatter/mod.rs create mode 100644 tools/kapi/src/formatter/plain.rs create mode 100644 tools/kapi/src/formatter/rst.rs create mode 100644 tools/kapi/src/formatter/shall.rs create mode 100644 tools/kapi/src/main.rs
Documentation/admin-guide/kernel-api-spec.rst +195 -3
@@ -31,7 +31,9 @@ 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. The + ``kapi`` tool (see `The kapi Tool`_) provides comprehensive extraction and + formatting capabilities. 4. **Enhance Debugging**: Provide detailed API information at runtime through debugfs for debugging and introspection.
@@ -71,6 +73,13 @@ The framework consists of several key components: - Type-safe parameter specifications - Context and constraint definitions +5. **kapi Tool** (``tools/kapi/``) + + - Userspace utility for extracting specifications + - Multiple input sources (source, binary, debugfs) + - Multiple output formats (plain, JSON, RST) + - Testing and validation utilities + Data Model ----------
@@ -344,8 +353,177 @@ Documentation Generation ------------------------ The framework exports specifications via debugfs that can be used -to generate documentation. Tools for automatic documentation generation -from specifications are planned for future development. +to generate documentation. The ``kapi`` tool provides comprehensive +extraction and formatting capabilities for kernel API specifications. + +The kapi Tool +============= + +Overview +-------- + +The ``kapi`` tool is a userspace utility that extracts and displays kernel API +specifications from multiple sources. It provides a unified interface to access +API documentation whether from compiled kernels, source code, or runtime systems. + +Installation +------------ + +Build the tool from the kernel source tree:: + + $ cd tools/kapi + $ cargo build --release + + # Optional: Install system-wide + $ cargo install --path . + +The tool requires Rust and Cargo to build. The binary will be available at +``tools/kapi/target/release/kapi``. + +Command-Line Usage +------------------ + +Basic syntax:: + + kapi [OPTIONS] [API_NAME] + +Options: + +- ``--vmlinux <PATH>``: Extract from compiled kernel binary +- ``--source <PATH>``: Extract from kernel source code +- ``--debugfs <PATH>``: Extract from debugfs (default: /sys/kernel/debug) +- ``-f, --format <FORMAT>``: Output format (plain, json, rst) +- ``-h, --help``: Display help information +- ``-V, --version``: Display version information + +Input Modes +----------- + +**1. Source Code Mode** + +Extract specifications directly from kernel source:: + + # Scan entire kernel source tree + $ kapi --source /path/to/linux + + # Extract from specific file + $ kapi --source kernel/sched/core.c + + # Get details for specific API + $ kapi --source /path/to/linux sys_sched_yield + +**2. Vmlinux Mode** + +Extract from compiled kernel with debug symbols:: + + # List all APIs in vmlinux + $ kapi --vmlinux /boot/vmlinux-5.15.0 + + # Get specific syscall details + $ kapi --vmlinux ./vmlinux sys_read + +**3. Debugfs Mode** + +Extract from running kernel via debugfs:: + + # Use default debugfs path + $ kapi + + # Use custom debugfs mount + $ kapi --debugfs /mnt/debugfs + + # Get specific API from running kernel + $ kapi sys_write + +Output Formats +-------------- + +**Plain Text Format** (default):: + + $ kapi sys_read + + Detailed information for sys_read: + ================================== + Description: Read from a file descriptor + + Detailed Description: + Reads up to count bytes from file descriptor fd into the buffer starting at buf. + + Execution Context: + - KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE + + Parameters (3): + + Available since: 1.0 + +**JSON Format**:: + + $ kapi --format json sys_read + { + "api_details": { + "name": "sys_read", + "description": "Read from a file descriptor", + "long_description": "Reads up to count bytes...", + "context_flags": ["KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE"], + "since_version": "1.0" + } + } + +**ReStructuredText Format**:: + + $ kapi --format rst sys_read + + sys_read + ======== + + **Read from a file descriptor** + + Reads up to count bytes from file descriptor fd into the buffer... + +Usage Examples +-------------- + +**Generate complete API documentation**:: + + # Export all kernel APIs to JSON + $ kapi --source /path/to/linux --format json > kernel-apis.json + + # Generate RST documentation for all syscalls + $ kapi --vmlinux ./vmlinux --format rst > syscalls.rst + + # List APIs from specific subsystem + $ kapi --source drivers/gpu/drm/ + +**Integration with other tools**:: + + # Find all APIs that can sleep + $ kapi --format json | jq '.apis[] | select(.context_flags[] | contains("SLEEPABLE"))' + + # Generate markdown documentation + $ kapi --format rst sys_mmap | pandoc -f rst -t markdown + +**Debugging and analysis**:: + + # Compare API between kernel versions + $ diff <(kapi --vmlinux vmlinux-5.10) <(kapi --vmlinux vmlinux-5.15) + + # Check if specific API exists + $ kapi --source . my_custom_api || echo "API not found" + +Implementation Details +---------------------- + +The tool extracts API specifications from three sources: + +1. **Source Code**: Parses KAPI specification macros using regular expressions +2. **Vmlinux**: Reads the ``.kapi_specs`` ELF section from compiled kernels +3. **Debugfs**: Reads from ``/sys/kernel/debug/kapi/`` filesystem interface + +The tool supports all KAPI specification types: + +- System calls (``DEFINE_KERNEL_API_SPEC``) +- IOCTLs (``DEFINE_IOCTL_API_SPEC``) +- Kernel functions (``KAPI_DEFINE_SPEC``) IDE Integration ---------------
@@ -357,6 +535,11 @@ Modern IDEs can use the JSON export for: - Context validation - Error code documentation +Example IDE integration:: + + # Generate IDE completion data + $ kapi --format json > .vscode/kernel-apis.json + Testing Framework -----------------
@@ -367,6 +550,15 @@ The framework includes test helpers:: kapi_test_api("kmalloc", test_cases); #endif +The kapi tool can verify specifications against implementations:: + + # Run consistency tests + $ cd tools/kapi + $ ./test_consistency.sh + + # Compare source vs binary specifications + $ ./compare_all_syscalls.sh + Best Practices ==============
tools/kapi/.gitignore new file +4 -0
@@ -0,0 +1,4 @@ +# Rust build artifacts +/target/ +**/*.rs.bk +
tools/kapi/Cargo.toml new file +19 -0
@@ -0,0 +1,19 @@ +[package] +name = "kapi" +version = "0.1.0" +edition = "2024" +authors = ["Sasha Levin <[email protected]>"] +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"
tools/kapi/src/extractor/debugfs.rs new file +442 -0
442 lines not on this page · raw message
tools/kapi/src/extractor/kerneldoc_parser.rs new file +694 -0
695 lines not on this page · raw message
tools/kapi/src/extractor/mod.rs new file +461 -0
461 lines not on this page · raw message
tools/kapi/src/extractor/source_parser.rs new file +213 -0
214 lines not on this page · raw message
tools/kapi/src/extractor/vmlinux/binary_utils.rs new file +180 -0
180 lines not on this page · raw message
tools/kapi/src/extractor/vmlinux/magic_finder.rs new file +102 -0
103 lines not on this page · raw message
tools/kapi/src/extractor/vmlinux/mod.rs new file +869 -0
654 lines not on this page · raw message
tools/kapi/src/formatter/json.rs new file +468 -0
468 lines not on this page · raw message
tools/kapi/src/formatter/mod.rs new file +145 -0
145 lines not on this page · raw message
tools/kapi/src/formatter/plain.rs new file +558 -0
558 lines not on this page · raw message
tools/kapi/src/formatter/rst.rs new file +621 -0
621 lines not on this page · raw message
tools/kapi/src/formatter/shall.rs new file +891 -0
891 lines not on this page · raw message
tools/kapi/src/main.rs new file +116 -0
116 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.50.1
Part of the diff is not shown here. View the raw message.