diff options
| author | Sasha Levin <sashal@kernel.org> | 2025-08-19 11:52:10 -0400 |
|---|---|---|
| committer | Sasha Levin <sashal@kernel.org> | 2026-10-07 18:26:44 -0400 |
| commit | 6d009bd85fa4e6dbad869e1cb707404968f3f20d (patch) | |
| tree | f764bac49d89c2553cda715c7f02dd58776478de /scripts | |
| parent | ce4c52682d78fc08c9b1e2217aae6f00fa02bab3 (diff) | |
| download | linux-next-6d009bd85fa4e6dbad869e1cb707404968f3f20d.tar.gz linux-next-6d009bd85fa4e6dbad869e1cb707404968f3f20d.zip | |
kernel/api: enable kerneldoc-based API specifications
Add support for extracting API specifications from kernel-doc comments
and generating C macro invocations for the kernel API specification
framework.
Changes include:
- New kdoc_apispec.py module for generating API spec macros
- Updates to tools/docs/kernel-doc to support the -apispec output format
- Build system integration in Makefile.build
- Support for API-specific sections in kernel-doc comments
kernel-doc recognises the KAPI sections only in -apispec mode, so its
other output formats are unchanged. With CONFIG_KAPI_SPEC=y, Kbuild
generates <file>.apispec.h for each built source that has a contexts:
or context-flags: line plus another KAPI section, and force-includes it
when compiling that source.
Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>
Diffstat (limited to 'scripts')
| -rw-r--r-- | scripts/Makefile.build | 26 |
1 files changed, 26 insertions, 0 deletions
diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 4349108e75e1..6fa9ae47fb2c 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -175,6 +175,32 @@ ifneq ($(KBUILD_EXTRA_WARN),) endif endif +ifeq ($(CONFIG_KAPI_SPEC),y) +# kernel-doc -apispec emits a spec only for comments with two or more KAPI +# sections; pick files with a contexts: (or context-flags:) line and one more +# KAPI section. +has-apispec = $(if $(strip $(1)),$(shell \ + grep -lE '^[[:space:]]*\*[[:space:]]*(contexts|context-flags):' $(1) 2>/dev/null | \ + xargs -r grep -lE '^[[:space:]]*\*[[:space:]]*(api-type|param|error|capability|signal|lock|state-trans|constraint|side-effect|long-desc):')) +apispec-c-files := $(call has-apispec, \ + $(patsubst $(obj)/%.o,$(src)/%.c, \ + $(filter-out %/built-in.a,$(real-obj-y)))) +apispec-y := $(patsubst $(src)/%.c,$(obj)/%.apispec.h,$(apispec-c-files)) +always-y += $(apispec-y) +targets += $(apispec-y) + +quiet_cmd_apispec = APISPEC $@ + cmd_apispec = PYTHONDONTWRITEBYTECODE=1 $(PYTHON3) $(KERNELDOC) -apispec \ + $(KDOCFLAGS) $< > $@ + +$(obj)/%.apispec.h: $(src)/%.c $(KERNELDOC) \ + $(wildcard $(srctree)/tools/lib/python/kdoc/*.py) FORCE + $(call if_changed,apispec) + +$(apispec-y:.apispec.h=.o): $(obj)/%.o: $(obj)/%.apispec.h +$(apispec-y:.apispec.h=.o): private c_flags += -include $(obj)/$*.apispec.h +endif + # Compile C sources (.c) # --------------------------------------------------------------------------- |