linux-kernel - Re: [RFC v2 01/22] 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] [thread-next>] [day] [month] [year] [list]

Message-ID: <874ivxuht8.fsf@trenco.lwn.net>
Date: Mon, 30 Jun 2025 13:53:55 -0600
From: Jonathan Corbet <corbet@....net>
To: Sasha Levin <sashal@...nel.org>, linux-kernel@...r.kernel.org
Cc: linux-doc@...r.kernel.org, linux-api@...r.kernel.org,
 workflows@...r.kernel.org, tools@...nel.org, Sasha Levin
 <sashal@...nel.org>
Subject: Re: [RFC v2 01/22] kernel/api: introduce kernel API specification
 framework

Sasha Levin <sashal@...nel.org> writes:

> 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>
> ---
>  Documentation/admin-guide/kernel-api-spec.rst |  507 ++++++

You need to add that file to index.rst in that directory or it won't be
pulled into the docs build.

Wouldn't it be nice to integrate all this stuff with out existing
kerneldoc mechanism...? :)

Thanks,

jon