Skip to contentSkip to conversation

Kernel API Specification Framework

RFC PATCH In review Sasha Levin 2 participants 9 messages Aug 25, 2025 – Sep 1, 2025

Subsystems (11)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index 929054df5212..e5aaa26d1b68 100644
@@ -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
index fed6cd812d79..51c8ff70b8a1 100644
@@ -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
index a36b7918a011..283ab11788d8 100644
@@ -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
index a409d4b66114..e3850d829343 100644
@@ -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
index 4fa0be732af1..8cc508adc9d5 100644
@@ -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
index ae2d2359b79e..93b6293c0259 100644
@@ -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
index 77f45e5d4413..403d0e09692f 100644
@@ -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
index 836320251219..481a5a73f1ff 100644
@@ -2108,6 +2108,8 @@ config TRACEPOINTS
 
 source "kernel/Kconfig.kexec"
 
+source "kernel/api/Kconfig"
+
 endmenu		# General setup
 
 source "arch/Kconfig"
kernel/Makefile +1 -0
index c60623448235..c100baacb1f0 100644
@@ -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
new file mode 100644
index 000000000000..fde25ec70e13
@@ -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
new file mode 100644
index 000000000000..4120ded7e5cf
@@ -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
\ No newline at end of file
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.

reviewer
#2 lore raw

Re: [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 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

Quoted 8 lines

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 ++++++

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
#3 lore raw

RFC PATCH v4 2/7 kernel/api: enable kerneldoc-based API specifications

In reply to Sasha Levin

This 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
index 4120ded7e5cf..312d35179c78 100644
@@ -4,4 +4,23 @@
 #
 
 # Core API specification framework
-obj-$(CONFIG_KAPI_SPEC)		+= kernel_api_spec.o
\ No newline at end of file
+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
\ No newline at end of file
scripts/Makefile.build +28 -0
index d0ee33a487be..8d54b685debe 100644
@@ -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
index fc3d46ef519f..286471622c6c 100755
@@ -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
index ea8914537ba0..9ac8e5beddaf 100644
@@ -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
#4 lore raw

RFC PATCH v4 3/7 kernel/api: add debugfs interface for kernel API specifications

In reply to Sasha Levin

Add 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
index fde25ec70e13..d2754b21acc4 100644
@@ -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
index 312d35179c78..396b2da1a109 100644
@@ -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
\ No newline at end of file
+endif
+
kernel/api/kapi_debugfs.c new file +334 -0

335 lines not on this page · raw message

Signature · 1 line
2.50.1
#5 lore raw

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
index 77ae87f36e84..c5eb0facdc3a 100644
@@ -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
#6 lore raw

RFC PATCH v4 5/7 mm/mlock: add API specification for mlock

In reply to Sasha Levin

Add kernel API specification for the mlock() system call.

---
 mm/mlock.c | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)
mm/mlock.c +134 -0
index a1d93ad33c6d..36eac7fec17d 100644
@@ -656,6 +656,140 @@ static __must_check int do_mlock(unsigned long start, size_t len, vm_flags_t fla
 	return 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
#7 lore raw

RFC PATCH v4 6/7 fs/exec: add API specification for execveat

In reply to Sasha Levin

Add kernel API specification for the execveat() system call.

---
 fs/exec.c | 594 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 594 insertions(+)
fs/exec.c +594 -0
index 2a1e5e4042a1..5dab6a801040 100644
@@ -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
#8 lore raw

RFC PATCH v4 7/7 tools/kapi: Add kernel API specification extraction tool

In reply to Sasha Levin

The 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
index 3a63f6711e27..9b452753111a 100644
@@ -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
new file mode 100644
index 000000000000..1390bfc12686
@@ -0,0 +1,4 @@
+# Rust build artifacts
+/target/
+**/*.rs.bk
+
tools/kapi/Cargo.toml new file +19 -0
new file mode 100644
index 000000000000..4e6bcb10d132
@@ -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.