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

Jonathan Corbet
2026-03-18T16:51:58Z

Sasha Levin <sashal@kernel.org> writes:

> On Tue, Mar 17, 2026 at 11:49:27AM -0600, Jonathan Corbet 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?
>>
>>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.
>
> Woops, I forgot to finish writing my reply to this :)
>
> Under the hood, kerneldoc specs are translated into those macros so they could
> be part of the build process and embedded into the resulting binary (both for
> documentation as well as the runtime validation).
>
> I don't think anyone would use the macro format directly, but as it's there
> anyway I figured I'd offer it as an option. Would it make sense to just hide it
> behind the scenes?

If there are two ways of doing it, people will use both ways. My
kneejerk reaction would be to hide the macros as an implementation
detail, but perhaps that's just me.

Thanks,

jon