195 lines · plain
1.. SPDX-License-Identifier: BSD-3-Clause2 3======================================================4Netlink specification support for raw Netlink families5======================================================6 7This document describes the additional properties required by raw Netlink8families such as ``NETLINK_ROUTE`` which use the ``netlink-raw`` protocol9specification.10 11Specification12=============13 14The netlink-raw schema extends the :doc:`genetlink-legacy <genetlink-legacy>`15schema with properties that are needed to specify the protocol numbers and16multicast IDs used by raw netlink families. See :ref:`classic_netlink` for more17information. The raw netlink families also make use of type-specific18sub-messages.19 20Globals21-------22 23protonum24~~~~~~~~25 26The ``protonum`` property is used to specify the protocol number to use when27opening a netlink socket.28 29.. code-block:: yaml30 31 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)32 33 name: rt-addr34 protocol: netlink-raw35 protonum: 0 # part of the NETLINK_ROUTE protocol36 37 38Multicast group properties39--------------------------40 41value42~~~~~43 44The ``value`` property is used to specify the group ID to use for multicast45group registration.46 47.. code-block:: yaml48 49 mcast-groups:50 list:51 -52 name: rtnlgrp-ipv4-ifaddr53 value: 554 -55 name: rtnlgrp-ipv6-ifaddr56 value: 957 -58 name: rtnlgrp-mctp-ifaddr59 value: 3460 61Sub-messages62------------63 64Several raw netlink families such as65:doc:`rt_link<../../networking/netlink_spec/rt_link>` and66:doc:`tc<../../networking/netlink_spec/tc>` use attribute nesting as an67abstraction to carry module specific information.68 69Conceptually it looks as follows::70 71 [OUTER NEST OR MESSAGE LEVEL]72 [GENERIC ATTR 1]73 [GENERIC ATTR 2]74 [GENERIC ATTR 3]75 [GENERIC ATTR - wrapper]76 [MODULE SPECIFIC ATTR 1]77 [MODULE SPECIFIC ATTR 2]78 79The ``GENERIC ATTRs`` at the outer level are defined in the core (or rt_link or80core TC), while specific drivers, TC classifiers, qdiscs etc. can carry their81own information wrapped in the ``GENERIC ATTR - wrapper``. Even though the82example above shows attributes nesting inside the wrapper, the modules generally83have full freedom to define the format of the nest. In practice the payload of84the wrapper attr has very similar characteristics to a netlink message. It may85contain a fixed header / structure, netlink attributes, or both. Because of86those shared characteristics we refer to the payload of the wrapper attribute as87a sub-message.88 89A sub-message attribute uses the value of another attribute as a selector key to90choose the right sub-message format. For example if the following attribute has91already been decoded:92 93.. code-block:: json94 95 { "kind": "gre" }96 97and we encounter the following attribute spec:98 99.. code-block:: yaml100 101 -102 name: data103 type: sub-message104 sub-message: linkinfo-data-msg105 selector: kind106 107Then we look for a sub-message definition called ``linkinfo-data-msg`` and use108the value of the ``kind`` attribute i.e. ``gre`` as the key to choose the109correct format for the sub-message:110 111.. code-block:: yaml112 113 sub-messages:114 name: linkinfo-data-msg115 formats:116 -117 value: bridge118 attribute-set: linkinfo-bridge-attrs119 -120 value: gre121 attribute-set: linkinfo-gre-attrs122 -123 value: geneve124 attribute-set: linkinfo-geneve-attrs125 126This would decode the attribute value as a sub-message with the attribute-set127called ``linkinfo-gre-attrs`` as the attribute space.128 129A sub-message can have an optional ``fixed-header`` followed by zero or more130attributes from an ``attribute-set``. For example the following131``tc-options-msg`` sub-message defines message formats that use a mixture of132``fixed-header``, ``attribute-set`` or both together:133 134.. code-block:: yaml135 136 sub-messages:137 -138 name: tc-options-msg139 formats:140 -141 value: bfifo142 fixed-header: tc-fifo-qopt143 -144 value: cake145 attribute-set: tc-cake-attrs146 -147 value: netem148 fixed-header: tc-netem-qopt149 attribute-set: tc-netem-attrs150 151Note that a selector attribute must appear in a netlink message before any152sub-message attributes that depend on it.153 154If an attribute such as ``kind`` is defined at more than one nest level, then a155sub-message selector will be resolved using the value 'closest' to the selector.156For example, if the same attribute name is defined in a nested ``attribute-set``157alongside a sub-message selector and also in a top level ``attribute-set``, then158the selector will be resolved using the value 'closest' to the selector. If the159value is not present in the message at the same level as defined in the spec160then this is an error.161 162Nested struct definitions163-------------------------164 165Many raw netlink families such as :doc:`tc<../../networking/netlink_spec/tc>`166make use of nested struct definitions. The ``netlink-raw`` schema makes it167possible to embed a struct within a struct definition using the ``struct``168property. For example, the following struct definition embeds the169``tc-ratespec`` struct definition for both the ``rate`` and the ``peakrate``170members of ``struct tc-tbf-qopt``.171 172.. code-block:: yaml173 174 -175 name: tc-tbf-qopt176 type: struct177 members:178 -179 name: rate180 type: binary181 struct: tc-ratespec182 -183 name: peakrate184 type: binary185 struct: tc-ratespec186 -187 name: limit188 type: u32189 -190 name: buffer191 type: u32192 -193 name: mtu194 type: u32195