linux-kernel - Re: [RFC PATCH v4 1/7] kernel/api: introduce kernel API specification framework

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <8d8b9cac-695c-469e-a831-c226b796430b@infradead.org>
Date: Mon, 1 Sep 2025 10:23:26 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Sasha Levin <sashal@...nel.org>, linux-api@...r.kernel.org,
 linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, tools@...nel.org
Subject: Re: [RFC PATCH v4 1/7] kernel/api: introduce kernel API specification
 framework

Hi Sasha,


On 8/25/25 11:14 AM, Sasha Levin wrote:
> 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.
> 
> Signed-off-by: Sasha Levin <sashal@...nel.org>
> ---
>  .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?


>  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
thanks.
-- 
~Randy