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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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