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

Mauro Carvalho Chehab
2026-03-18T06:24:19Z

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