Re: [PATCH net-next v2 06/11] doc/netlink: Document the sub-message format for netlink-raw

[Donald Hunter <donald.hunter@gmail.com>]

Jakub Kicinski <kuba@kernel.org> writes:

> On Mon, 11 Dec 2023 16:40:34 +0000 Donald Hunter wrote:
>> +Sub-messages
>> +------------
>> +
>> +Several raw netlink families such as rt_link and tc have type-specific
>> +sub-messages. These sub-messages can appear as an attribute in a top-level or a
>> +nested attribute space.
>> +
>> +A sub-message attribute uses the value of another attribute as a selector key to
>> +choose the right sub-message format. For example if the following attribute has
>> +already been decoded:
>
> We may want to explain why we call this thing "sub-message". How about:
>
>   Several raw netlink families such as rt_link and tc use attribute
>   nesting as an abstraction to carry module specific information.
>   Conceptually it looks as follows::
>
>     [OUTER NEST OR MESSAGE LEVEL]
>       [GENERIC ATTR 1]
>       [GENERIC ATTR 2]
>       [GENERIC ATTR 3]
>       [GENERIC ATTR - wrapper]
>         [MODULE SPECIFIC ATTR 1]
>         [MODULE SPECIFIC ATTR 2]
>
>   The GENERIC ATTRs at the outer level are defined in the core (or rt_link
>   or core TC), while specific drivers / TC classifiers, qdiscs etc. can
>   carry their own information wrapped in the "GENERIC ATTR - wrapper".
>   Even though the example above shows attributes nesting inside the wrapper,
>   the modules generally have full freedom of defining the format of the nest.
>   In practice payload of the wrapper attr has very similar characteristics
>   to a netlink message. It may contain a fixed header / structure, netlink
>   attributes, or both. Because of those shared characteristics we refer
>   to the payload of the wrapper attribute as a sub-message.

I'll incorporate into next revision. Thanks!

>> +A sub-message attribute uses the value of another attribute as a selector key to
>> +choose the right sub-message format. For example if the following attribute has
>> +already been decoded: