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

[Sasha Levin <sashal@kernel.org>]

On Wed, Mar 18, 2026 at 07:00:55AM +0100, Mauro Carvalho Chehab wrote:
>On Tue, 17 Mar 2026 11:49:27 -0600
>Jonathan Corbet <corbet@lwn.net> wrote:
>> 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.

So this is exactly what happens under the hood :) kerneldoc outputs these
macros and they get compiled ito the binary.

I exposed the macros as an option since they're there anyway, but I'm happy to
hide them as internal plumbing too.

-- 
Thanks,
Sasha