Re: [PATCH 1/9] kernel/api: introduce kernel API specification framework

[Mauro Carvalho Chehab]

On Tue, 17 Mar 2026 11:49:27 -0600
Jonathan Corbet <corbet@xxxxxxx> wrote:

> Sasha Levin <sashal@xxxxxxxxxx> 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 <sashal@xxxxxxxxxx>
> > +: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