linux-kernel - Re: [RFC v3 2/4] kernel/api: enable kerneldoc-based API specifications

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 for Android: free password hash cracker in your pocket

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

Message-ID: <4777f4d7-f1c6-4345-92b2-0ba5d6563ee2@infradead.org>
Date: Sun, 20 Jul 2025 17:55:05 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Sasha Levin <sashal@...nel.org>, linux-kernel@...r.kernel.org
Cc: linux-doc@...r.kernel.org, linux-api@...r.kernel.org, tools@...nel.org
Subject: Re: [RFC v3 2/4] kernel/api: enable kerneldoc-based API
 specifications

Hi Sasha,

I would like to ask a few questions to try to clarify/understand, please.

On 7/11/25 4:42 AM, Sasha Levin wrote:
> Allow kernel developers to write API specifications directly in
> kerneldoc comments, which are automatically converted to machine-readable
> C macros during build.
> 
> Signed-off-by: Sasha Levin <sashal@...nel.org>
> ---
>  kernel/api/Makefile              |  21 +-
>  scripts/Makefile.build           |  28 ++
>  scripts/generate_api_specs.sh    |  59 +++
>  scripts/kernel-doc.py            |   5 +
>  scripts/lib/kdoc/kdoc_apispec.py | 623 +++++++++++++++++++++++++++++++
>  scripts/lib/kdoc/kdoc_output.py  |   5 +-
>  scripts/lib/kdoc/kdoc_parser.py  |  54 ++-
>  7 files changed, 791 insertions(+), 4 deletions(-)
>  create mode 100755 scripts/generate_api_specs.sh
>  create mode 100644 scripts/lib/kdoc/kdoc_apispec.py
> 

[snip]

> diff --git a/scripts/Makefile.build b/scripts/Makefile.build
> index a6461ea411f7a..5c0e44d1b6dbc 100644
> --- a/scripts/Makefile.build
> +++ b/scripts/Makefile.build
> @@ -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)))

1. One must build a kernel (with some desired .config file) to use/test this,
correct?

2. It looks like it only checks .c files, omitting header files. (?)
Some APIs are only present in header files (e.g., all of <linux/list.h> is
either macros or inline functions).


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

3a. included files: does this catch the (rare) use of a C file doing
#include <path to some other C file> ?

3b. Quite a few makefiles generate final .o files with a different name
from the source files. It looks like that is handled above by looking
for the first (or intermediate) .o file for each .c file, so the final
.o file with a different name is ignored (or at least doesn't come into
play here). Yes?


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

[snip]

Thanks.

-- 
~Randy