Commit de2d9874 authored by Donald Hunter's avatar Donald Hunter Committed by Jakub Kicinski
Browse files

doc/netlink: Add sub-message support to netlink-raw 



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

Reviewed-by: default avatarJakub Kicinski <kuba@kernel.org>
Signed-off-by: default avatarDonald Hunter <donald.hunter@gmail.com>
Link: https://lore.kernel.org/r/20231215093720.18774-3-donald.hunter@gmail.com


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent 62691b80

Documentation/netlink/netlink-raw.yaml

+62 −3
Original line number Diff line number Diff line
@@ -126,8 +126,10 @@ properties: 
              name:

                type: string

              type:

                description: The netlink attribute type

                enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ]

                description: |

                  The netlink attribute type. Members of type 'binary' or 'pad'

                  must also have the 'len' property set.

                enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary, pad ]

              len:

                $ref: '#/$defs/len-or-define'

              byte-order:
@@ -150,6 +152,14 @@ properties: 
                  the right formatting mechanism when displaying values of this

                  type.

                enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]

            if:

              properties:

                type:

                  oneOf:

                    - const: binary

                    - const: pad

            then:

              required: [ len ]

        # End genetlink-legacy



  attribute-sets:
@@ -202,7 +212,8 @@ properties: 
                description: The netlink attribute type

                enum: [ unused, pad, flag, binary, bitfield32,

                        u8, u16, u32, u64, s8, s16, s32, s64,

                        string, nest, array-nest, nest-type-value ]

                        string, nest, array-nest, nest-type-value,

                        sub-message ]

              doc:

                description: Documentation of the attribute.

                type: string
@@ -261,6 +272,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

              # End netlink-raw



      # Make sure name-prefix does not appear in subsets (subsets inherit naming)

      dependencies:
@@ -283,6 +305,43 @@ properties: 
            items:

              required: [ type ]



  # Start netlink-raw

  sub-messages:

    description: Definition of sub message attributes

    type: array

    items:

      type: object

      additionalProperties: False

      required: [ name, formats ]

      properties:

        name:

          description: Name of the sub-message definition

          type: string

        formats:

          description: Dynamically selected format specifiers

          type: array

          items:

            type: object

            additionalProperties: False

            required: [ value ]

            properties:

              value:

                description: |

                  Value to match for dynamic selection of sub-message format

                  specifier.

                type: string

              fixed-header:

                description: |

                  Name of the struct definition to use as the fixed header

                  for the sub message.

                type: string

              attribute-set:

                description: |

                  Name of the attribute space from which to resolve attributes

                  in the sub message.

                type: string

  # End netlink-raw



  operations:

    description: Operations supported by the protocol.

    type: object