On Sat, Mar 14, 2026 at 10:44:35PM +0000, David Laight wrote:
On Sat, 14 Mar 2026 11:18:22 -0700
Jakub Kicinski <[email protected]> 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
