On Tue, 17 Mar 2026 11:49:27 -0600 Jonathan Corbet <[email protected]> wrote:
> Sasha Levin <[email protected]> writes: > > > 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) > > - Export of specifications via debugfs for tooling integration > > - Support for both internal kernel APIs and system calls > > So I'll confess I have only scanned over the implementation, but I have > some thoughts on the earlier stuff. > > [...] > > > diff --git a/Documentation/dev-tools/kernel-api-spec.rst > > b/Documentation/dev-tools/kernel-api-spec.rst > > new file mode 100644 > > index 0000000000000..7c0c1694f1f4a > > --- /dev/null > > +++ b/Documentation/dev-tools/kernel-api-spec.rst > > @@ -0,0 +1,482 @@ > > +.. SPDX-License-Identifier: GPL-2.0 > > + > > +====================================== > > +Kernel API Specification Framework > > +====================================== > > + > > +:Author: Sasha Levin <[email protected]> > > +:Date: June 2025 > > Has it not changed since then? > > > +.. contents:: Table of Contents > > + :depth: 3 > > + :local: > > + > > +Introduction > > +============ > > [...] > > > +Usage Guide > > +=========== > > + > > +Basic API Specification > > +----------------------- > > + > > +API specifications are written as KAPI-annotated kerneldoc comments > > directly in > > +the source file, immediately preceding the function implementation. The > > ``kapi`` > > +tool extracts these annotations to produce structured specifications. > > + > > +.. code-block:: c > > + > > + /** > > + * kmalloc - allocate kernel memory > > + * @size: Number of bytes to allocate > > + * @flags: Allocation flags (GFP_*) > > Given that the text thus far has talked about user-space API validation, > it's a bit surprising to see an internal function used as an example. > > Also, maybe it should be kmalloc_obj()? <runs away> > > > + * context-flags: KAPI_CTX_PROCESS | KAPI_CTX_SOFTIRQ | > > KAPI_CTX_HARDIRQ > > + * param-count: 2 > > param-count is two, but you only document one of them? > > > + * param: size > > + * type: KAPI_TYPE_UINT > > + * flags: KAPI_PARAM_IN > > + * constraint-type: KAPI_CONSTRAINT_RANGE > > + * range: 0, KMALLOC_MAX_SIZE > > + * > > + * error: ENOMEM, Out of memory > > + * desc: Insufficient memory available for the requested allocation. > > + */ > > Honest question: can this be made a bit easier for people to create, > with less shift-key wear? My biggest worry with a system like this is > that people won't take the time to create and maintain the entries, so > anything that would ease the task would help. Is there an impediment to > something like: > > contexts: process, softirq, hardirq > > param: size > type: uint, input > constraint: range(0, KMALLOC_MAX_SIZE) > > See what I'm getting at? ISTM that your DSL could be made a bit less > verbose and shouty while being just as well defined, but perhaps I'm > missing something? > > Even better, of course, would be to add a "description" field for each > parameter, and allow that rather than the @param description that > kerneldoc currently uses. That would keep all the information together, > at the minor cost of adding another significant complication to the > kernel-doc script. Mauro won't mind :) No, I won't ;-) It sounds a lot better to use kernel-doc also for kAPI than to have an independent tool. It is also very confusing if we end with a kernel-doc-like format that it is not parsed by kernel-doc. > > > + void *kmalloc(size_t size, gfp_t flags) > > + { > > + /* Implementation */ > > + } > > + > > +Alternatively, specifications can be defined using the > > ``DEFINE_KERNEL_API_SPEC`` > > +macro for compiled-in specs that are stored in the ``.kapi_specs`` ELF > > section: > > + > > +.. code-block:: c > > + > > + #include <linux/kernel_api_spec.h> > > + > > + DEFINE_KERNEL_API_SPEC(sys_open) > > + KAPI_DESCRIPTION("Open or create a file") > > + KAPI_CONTEXT(KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE) > > + /* ... parameter, error, constraint definitions ... */ > > + KAPI_END_SPEC > > So the reason for two completely separate mechanisms is not entirely > clear to me. The kerneldoc variant is essentially documentation, while > the macro stuff is to be built into the executable? What if you want > both? You can easily add support at kernel-doc to output such macros. All you need is to create a new class derived from OutputFormat and make it produce any different output format, including: #include <linux/kernel_api_spec.h> DEFINE_KERNEL_API_SPEC(sys_open) KAPI_DESCRIPTION("Open or create a file") KAPI_CONTEXT(KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE) /* ... parameter, error, constraint definitions ... */ KAPI_END_SPEC I'd say that converting from such output to `.kapi_specs`` ELF section itself and/or to sysfs/debugfs - e.g. something that would require to compile or be linked with Kernel's compiled binaries should be done by a separate tool, but we should aim to have a singe tool to process kernel documentation markups. It is hard enough to maintain just one tool - and to have people actually writing documentation. Having a second one to handle it, with a different format will likely increase a lot the documentation burden. > It would be nice to only have one way if at all possible; I'm sure that > crossed your mind at some point :) If there have to be two, having both > examples describe the same function would make the parallels more clear. > > > +System Call Specification > > +------------------------- > > + > > +System calls are documented inline in the implementation file (e.g., > > ``fs/open.c``) > > +using KAPI-annotated kerneldoc comments. When > > ``CONFIG_KAPI_RUNTIME_CHECKS`` is > > +enabled, the ``SYSCALL_DEFINEx`` macros automatically look up the > > specification > > +and validate parameters before and after the syscall executes. > > + > > +IOCTL Specification > > +------------------- > > + > > +IOCTLs use the same annotation approach with additional structure field > > +specifications > > This might be a really good place for an example > > [...] > > > +Usage Examples > > +-------------- > > + > > +Query specific API:: > > + > > + $ cat /sys/kernel/debug/kapi/apis/kmalloc/specification > > + API: kmalloc > > + Version: 3.0 > > + Description: Allocate kernel memory > > + > > + Parameters: > > + [0] size (size_t, in): Number of bytes to allocate > > + Range: 0 - 4194304 > > + [1] flags (flags, in): Allocation flags (GFP_*) > > + Mask: 0x1ffffff > > Ah, you do document that second parameter somewhere :) > > > + Returns: pointer - Pointer to allocated memory or NULL > > + > > + Errors: > > + ENOMEM: Out of memory > > + > > + Context: process, softirq, hardirq > > + > > + Side Effects: > > + - Allocates memory from kernel heap > > That part wasn't in your example > > > +Export all specifications:: > > + > > + $ cat /sys/kernel/debug/kapi/export/all.json > kernel-apis.json > > + > > +Enable validation for specific API:: > > + > > + $ echo 1 > /sys/kernel/debug/kapi/apis/kmalloc/validate > > + > > +Performance Considerations > > +========================== > > + > > +Memory Overhead > > +--------------- > > + > > +Each API specification consumes approximately 400-450KB of memory due to > > the > > +fixed-size arrays in ``struct kernel_api_spec``. With the current 4 syscall > > +specifications, total memory usage is approximately 1.7MB. Consider: > > Ouch. > > > +Documentation Generation > > +------------------------ > > + > > +The framework exports specifications via debugfs that can be used > > +to generate documentation. Tools for automatic documentation generation > > +from specifications are planned for future development. > > Documentation always comes last :) > > Interesting stuff. > > jon Thanks, Mauro
