Re: [PATCH net-next v1 2/6] doc/netlink: Add sub-message support to netlink-raw

[Jakub Kicinski <kuba@kernel.org>]

On Thu, 30 Nov 2023 21:49:54 +0000 Donald Hunter wrote:
> Add a 'sub-message' attribute type with a selector that supports
> polymorphic attribute formats for raw netlink families like tc.
> 
> 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:
> 
>   { "kind": "gre" }
> 
> and we encounter the following attribute spec:
> 
>   -
>     name: data
>     type: sub-message
>     sub-message: linkinfo-data-msg
>     selector: kind
> 
> Then we look for a sub-message definition called 'linkinfo-data-msg' and
> use the value of the 'kind' attribute i.e. 'gre' as the key to choose
> the correct format for the sub-message:
> 
>   sub-messages:
>     name: linkinfo-data-msg
>     formats:
>       -
>         value: bridge
>         attribute-set: linkinfo-bridge-attrs
>       -
>         value: gre
>         attribute-set: linkinfo-gre-attrs
>       -
>         value: geneve
>         attribute-set: linkinfo-geneve-attrs
> 
> This would decode the attribute value as a sub-message with the
> attribute-set called 'linkinfo-gre-attrs' as the attribute space.
> 
> A sub-message can have an optional 'fixed-header' followed by zero or
> more attributes from an attribute-set. For example the following
> 'tc-options-msg' sub-message defines message formats that use a mixture
> of fixed-header, attribute-set or both together:
> 
>   sub-messages:
>     -
>       name: tc-options-msg
>       formats:
>         -
>           value: bfifo
>           fixed-header: tc-fifo-qopt
>         -
>           value: cake
>           attribute-set: tc-cake-attrs
>         -
>           value: netem
>           fixed-header: tc-netem-qopt
>           attribute-set: tc-netem-attrs

SGTM, could you add all the info from the commit message somewhere 
in the documentation? Perhaps a new section at the end of
Documentation/userspace-api/netlink/specs.rst

> @@ -261,6 +262,17 @@ properties:
>                  description: Name of the struct type used for the attribute.
>                  type: string
>                # End genetlink-legacy
> +              # Start netlink-raw
> +              sub-message:
> +                description:
> +                  Name of the sub-message definition to use for the attribute.
> +                type: string
> +              selector:
> +                description:
> +                  Name of the attribute to use for dynamic selection of sub-message
> +                  format specifier.
> +                type: string

We can leave it for later either way, but have you seen any selectors
which would key on an integer, rather than a string?