Re: [RFC v2 01/22] kernel/api: introduce kernel API specification framework

[Jonathan Corbet <corbet@lwn.net>]

[Adding some of the ELISA folks, who are working in a related area and
might have thoughts on this.  You can find the patch series under
discussion at:

  https://lore.kernel.org/all/20250624180742.5795-1-sashal@kernel.org

]

Sasha Levin <sashal@kernel.org> writes:

> 1. Add new section patterns to doc_sect regex in to include API
> specification sections: api-type, api-version, param-type, param-flags,
> param-constraint, error-code, capability, signal, lock-req, since...

Easily enough done - you can never have too many regexes :)

> 2. Create new output module (scripts/lib/kdoc/kdoc_apispec.py?) to
> generate C macro invocations from parsed data.
>
> Which will generate output like:
>
>     DEFINE_KERNEL_API_SPEC(function_name)
>         KAPI_DESCRIPTION("...") 
>         KAPI_PARAM(0, "name", "type", "desc")
>             KAPI_PARAM_TYPE(KAPI_TYPE_INT)
>             KAPI_PARAM_FLAGS(KAPI_PARAM_IN)
>         KAPI_PARAM_END
>     KAPI_END_SPEC 

Also shouldn't be all that hard.

> 3. And then via makefile we can: 
>     - Generate API specs from kerneldoc comments
>     - Include generated specs conditionally based on CONFIG_KERNEL_API_SPEC
>
> Allowing us to just have these in the relevant source files:
>     #ifdef CONFIG_KERNEL_API_SPEC
>     #include "socket.apispec.h"
>     #endif

...seems like it should work.

> In theory, all of that will let us have something like the following in
> kerneldoc:
>
> - @api-type: syscall
> - @api-version: 1
> - @context-flags: KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE
> - @param-type: family, KAPI_TYPE_INT
> - @param-flags: family, KAPI_PARAM_IN
> - @param-range: family, 0, 45
> - @param-mask: type, SOCK_TYPE_MASK | SOCK_CLOEXEC | SOCK_NONBLOCK
> - @error-code: -EAFNOSUPPORT, "Address family not supported"
> - @error-condition: -EAFNOSUPPORT, "family < 0 || family >= NPROTO"
> - @capability: CAP_NET_RAW, KAPI_CAP_GRANT_PERMISSION
> - @capability-allows: CAP_NET_RAW, "Create SOCK_RAW sockets"
> - @since: 2.0
> - @return-type: KAPI_TYPE_FD
> - @return-check: KAPI_RETURN_ERROR_CHECK
>
> How does it sound? I'm pretty excited about the possiblity to align this
> with kerneldoc. Please poke holes in the plan :)

I think we could do it without all the @signs.  We'd also want to see
how well we could integrate that information with the minimal structure
we already have: getting the return-value information into the Returns:
section, for example, and tying the parameter constraints to the
parameter descriptions we already have.

The other thing I would really like to see, to the extent we can, is
that a bunch of patches adding all this data to the source will actually
be accepted by the relevant maintainers.  It would be a shame to get all
this infrastructure into place, then have things stall out due to
maintainer pushback.  Maybe you should start by annotating the
scheduler-related system calls; if that works the rest should be a piece
of cake :)

Thanks,

jon