Thoughts on YAML netlink bindings?

[kuba-moo]

I posted an RFC in the kernel for defining the netlink protocols in YAML [1] so that user space languages which can't include the C header did not have to manually reproduce the APIs. I'm curious what your thoughts are. [1] https://lore.kernel.org/all/[email protected]/

[svinota]

I would love to have such protocol manifests. There are some questions that come first:

1. distribution: ideally as a set of files on procfs or sysfs (not too hard to implement, like the same for the kernel config)?
2. arrays: there are multiple ways of working with arrays in existing protocols (H for header, D for data): HDDD, HHDHDHD, HDHDHD; sometimes in one protocol; a protocol manifest should somehow define that
3. conditional packet structure: sometimes it's a simple dependency of an NLA on another NLA, sometimes it's a dependency on some arbitrary field
4. …

Would be there a working place to discuss the initiative, I would like to participate.

[kuba-moo]

ad 1. I haven't made any decisions on distribution. Embedded people always complain about the kernel size (which is one of the reasons why in-kernel netlink policies are perhaps a little less expressive than they could be, and we jump thru extra hoops for per command policies...) Putting it in /sys is an option, another is treating it like a uAPI header and installing in some equivalent of /usr/include. I'm hoping to have a discussion on the topic at the kernel maintainers' summit in Sept. I do have a slight preference for bundling of the YAML with the application at build time (hence /usr/include) because netlink families in the kernel have a choice of what to do with unknown attributes (ignore or reject). Reading the "running kernel's YAML" moves that policy decision to user space as it does not know how to render unknown attrs so it needs to raise an exception or silently drop them. So we'd be making the policy decision both in the kernel and user space. ad 2. Yeah, UGH. I have a few formats defined. Haven't gotten to HDDDDD, yet. I'll need to document all of them well. And tell people to only use one (with automated parsing HDHDHDHD is actually quite tempting because the extra wrapping is only for "logical grouping"/parsing pleasure and automated parser does not care for pleasure) :/ ad 3. After much anguish I decided that defining the field dependencies in the YAML is very hard and very prone to going stale. I won't even define that a field is required or always present. I believe that's the same decision that gRPC people came to.

So far the discussion is on the list. I'll keep you posted (i.e. CCed). It's a big project so I'd like to make it more collaborative but haven't figured out how. So sticking to bi-weekly postings to the ML for now.

[svinota]

Btw, @kuba-moo — some years ago I tried to start a group here at github to document netlink protocols, but it didn't go (for many reasons).

Do you think it would be meaningful either to revive it, or to start from scratch? Just to have a public repo with all related docs in rst + examples.

[svinota]

Regarding arrays:

https://github.com/svinota/pyroute2/blob/823474b71a62b0d34ff0e676a6c26d38f0791d70/pyroute2/netlink/init.py#L307-L338

[kuba-moo]

Do you think it would be meaningful either to revive it, or to start from scratch? Just to have a public repo with all related docs in rst + examples.

I was planning on generating the docs based on the YAML schema for the new genetlink families going forward. Integrate with the kernel Sphinx-based doc system to extract the descriptions (Sphinx being in Python perhaps it'd be something I could enlist your help with? 😬) The documentation based on the YAML descriptions will likely be lower quality than hand-written but experience teaches that it's the best way to force people to write any docs at all (the YAML validation will throw an error if attribute has no description). Perhaps we could still allow mixing with hand written docs, like we do with kernel doc comments, too.

For existing families documentation would be most welcome. If the patch I posted yesterday goes in we can start funneling documentation for the actual interfaces into the same directory.

[svinota]

Ok, you can count on me with sphinx docs for sure.

Which way do you prefer to communicate on this project? The net-next maillist, or?

Moreover, I plan to employ netlink mocking for interactive docs [1] and already use mock objects to test example code snippets in the docs [2] — maybe some of this experience could be useful for the kernel netlink docs as well.

[1] https://lab.pyroute2.org/iproute.html — in progress; the code is being executed in the browser; netlink packets are being compiled and parsed there by Python running over WebAssembly [2] https://beta.pyroute2.org/ndb.html — built docs; sources: https://github.com/svinota/pyroute2/blob/6bea325aa4b9f5773c0d34ab3b164f0a66c62b6d/pyroute2/ndb/main.py#L189-L201

[kuba-moo]

I put up the WIP tree on GH, netdev ML would be best for communication because I reckon that's where most kernel experts will pay attention (or at least we can CC them easily), but hopefully GH would also give me sufficient notifications to notice. The tree is here - https://github.com/kuba-moo/ynl Absolutely unfinished, messy work in progress.

Feel free to have a stab at the sphinx stuff already (I think it'd have to go into Documentation/sphinx/ ?), but note that I'm planning to reorganize the sections in YAML moderately to open a path to supporting non generic netlink in the future, so if you start now you may need to update later. I haven't put too much effort into the in-spec docs, yet, I think the genetlink has the most "description" attrs right now: https://github.com/kuba-moo/ynl/blob/main/Documentation/netlink/bindings/genetlink.yaml

Wow, the mocking looks pretty sweet. For the kernel tho the NBD docs may be a little implementation-specific, did you have in mind stripping them a little or using as is?

[svinota]

The NDB docs are just an example, I don't think it's meaningful to mention NDB in the kernel docs, surely :))

Ok, thanks, I'll take at the repo asap.

[kuba-moo]

It's been slow progress but the first chunk of YAML specs has been merged for 6.3: https://docs.kernel.org/next/userspace-api/netlink/index.html (I'm linking to docs cause I put some extra effort in to avoid re-explaining. LMK if things are unclear!)