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

[Jakub Kicinski <kuba@kernel.org>]

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.

> +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: