[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@xxxxxxxxxx ] Sasha Levin <sashal@xxxxxxxxxx> 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
