From ce4c52682d78fc08c9b1e2217aae6f00fa02bab3 Mon Sep 17 00:00:00 2001 From: Sasha Levin Date: Fri, 11 Jul 2025 07:42:45 -0400 Subject: kernel/api: introduce kernel API specification framework Add a 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) - Support for both internal kernel APIs and system calls The framework stores specifications in a dedicated ELF section and provides infrastructure for: - Runtime querying of API documentation - Integration with existing SYSCALL_DEFINE macros A KUnit suite (CONFIG_KAPI_KUNIT_TEST) covers registration, lookup, parameter and return value validation, and JSON export. No specifications are added here; subsequent patches add them for individual syscalls. With CONFIG_KAPI_SPEC=n the SYSCALL_DEFINEx() expansion is unchanged. CONFIG_KAPI_RUNTIME_CHECKS is a debug option: a syscall whose arguments violate its specification returns -EINVAL without running. Assisted-by: LLM Signed-off-by: Sasha Levin --- include/linux/kapi_syscall.h | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 include/linux/kapi_syscall.h (limited to 'include/linux/kapi_syscall.h') diff --git a/include/linux/kapi_syscall.h b/include/linux/kapi_syscall.h new file mode 100644 index 000000000000..bc9387e0e052 --- /dev/null +++ b/include/linux/kapi_syscall.h @@ -0,0 +1,35 @@ +/* SPDX-License-Identifier: GPL-2.0 */ +/* + * Copyright (C) 2026 Sasha Levin + * + * Spec lookup and syscall validation entry points of the kernel API + * specification framework, kept apart from so that + * can declare them cheaply. + */ + +#ifndef _LINUX_KAPI_SYSCALL_H +#define _LINUX_KAPI_SYSCALL_H + +#include + +struct kernel_api_spec; + +const struct kernel_api_spec *kapi_get_spec(const char *name); + +#ifdef CONFIG_KAPI_RUNTIME_CHECKS +int kapi_validate_syscall_params(const struct kernel_api_spec *spec, + const s64 *params, int param_count); +int kapi_validate_syscall_return(const struct kernel_api_spec *spec, s64 retval); +#else +static inline int kapi_validate_syscall_params(const struct kernel_api_spec *spec, + const s64 *params, int param_count) +{ + return 0; +} +static inline int kapi_validate_syscall_return(const struct kernel_api_spec *spec, s64 retval) +{ + return 0; +} +#endif + +#endif /* _LINUX_KAPI_SYSCALL_H */ -- cgit v1.2.3