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

doc/netlink: Document the sub-message format for netlink-raw 



Document the spec format used by netlink-raw families like rt and tc.

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-4-donald.hunter@gmail.com


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

Documentation/userspace-api/netlink/netlink-raw.rst

+95 −1
Original line number Diff line number Diff line
@@ -14,7 +14,8 @@ Specification 
The netlink-raw schema extends the :doc:`genetlink-legacy <genetlink-legacy>`

schema with properties that are needed to specify the protocol numbers and

multicast IDs used by raw netlink families. See :ref:`classic_netlink` for more

information.

information. The raw netlink families also make use of type-specific

sub-messages.



Globals

-------
@@ -56,3 +57,96 @@ group registration. 
      -

        name: rtnlgrp-mctp-ifaddr

        value: 34



Sub-messages

------------



Several raw netlink families such as

:doc:`rt_link<../../networking/netlink_spec/rt_link>` and

:doc:`tc<../../networking/netlink_spec/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 to define the format of the nest. In practice the 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:



.. code-block:: json



  { "kind": "gre" }



and we encounter the following attribute spec:



.. code-block:: yaml



  -

    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:



.. code-block:: yaml



  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:



.. code-block:: yaml



  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



Note that a selector attribute must appear in a netlink message before any

sub-message attributes that depend on it.