On Sun, 15 Mar 2026 02:36:51 -0400
Sasha Levin <sashal@kernel.org> wrote:
> On Sat, Mar 14, 2026 at 11:18:22AM -0700, Jakub Kicinski 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.
>
> Once the API is in a machine-readable format, we can write formatters to
> output whatever downstream tools need.
Kernel-doc already does that. The way it works is that it handles
kernel-doc markups on two steps:
- first step: parse kernel-doc markups, function prototypes and data
types for variables, typedefs, structs, unions, enums.
This is done inside tools/lib/python/kdoc/kdoc_parser.py.
The documentation is stored in memory as a list of documentation
entries. Each element there belongs to class KdocItem.
It is trivial to output its content in JSON or YAML format. I
submitted a path series a while ago doing exactly that, aiming to help
writing unittests for first step:
https://lore.kernel.org/linux-doc/7648cb5f5a1b501d9ae9a57b4d8dbeb7273d9097.1770128540.git.mchehab+huawei@kernel.org/
I'm planing to rebase such patch series on the top of my latest
kernel-doc patch series.
- second step: output generation. There is an abstract class named
OutputFormat which contains the following output methods:
def out_doc(self, fname, name, args):
"""Outputs a DOC block."""
def out_function(self, fname, name, args):
"""Outputs a function."""
def out_enum(self, fname, name, args):
"""Outputs an enum."""
def out_var(self, fname, name, args):
"""Outputs a variable."""
def out_typedef(self, fname, name, args):
"""Outputs a typedef."""
def out_struct(self, fname, name, args):
"""Outputs a struct."""
Producing a different output is as easy as doing:
class MyFormat(OutputFormat):
...
def out_var(self, fname, name, args):
self.data =+ f"whatever {name}"
...
Thanks,
Mauro