Re: [PATCH 0/9] Kernel API Specification Framework

[Sasha Levin <sashal@kernel.org>]

On Sat, Mar 14, 2026 at 10:44:35PM +0000, David Laight wrote:
>On Sat, 14 Mar 2026 11:18:22 -0700
>Jakub Kicinski <kuba@kernel.org> wrote:
>
>> On Fri, 13 Mar 2026 11:09:10 -0400 Sasha Levin wrote:
>> > This enables static analysis tools to verify userspace API usage at compile
>> > time, test generation based on formal specifications, consistent error handling
>> > validation, automated documentation generation, and formal verification of
>> > kernel interfaces.
>>
>> Could you give some examples? We have machine readable descriptions for
>> Netlink interfaces, we approached syzbot folks and they did not really
>> seem to care for those.
>
>The whole thing reminds me of doxygen comment blocks.
>They tend to make it hard to read the source files, hard to search
>the source files (due to all the extra matches) and are pretty much
>always out of date.
>
>The kerndoc comment blocks for trivial helper functions are hard enough
>to keep up to date.
>
>The only way even parameter descriptions are going to stay correct is if the
>compiler is using the definition and only the comment part is extra.
>For error returns you'll need the documentation to be at the return site.

When CONFIG_KAPI_RUNTIME_CHECKS is enabled, the specs are enforced at
the syscall boundary. The SYSCALL_DEFINEx macro grows a wrapper that
calls kapi_validate_syscall_params() before the real implementation and
kapi_validate_syscall_return() after it. Parameter constraints (ranges,
valid flag masks, alignment) are checked on every syscall entry, and
return values are validated against the documented success/error ranges
on every exit.

If a spec goes stale, it has runtime consequences. A new flag bit added
without updating the spec's valid_mask means callers using that flag get
EINVAL, which any test exercising that path catches immediately. An
implementation returning an undocumented error code triggers a warning
from the return validation.

The selftest in the series (tools/testing/selftests/kapi/test_kapi.c)
exercises this with real syscalls, both valid and invalid inputs,
verifying the validation layer catches violations.

-- 
Thanks,
Sasha