1.. SPDX-License-Identifier: BSD-3-Clause 2 3====================================================== 4Netlink specification support for raw Netlink families 5====================================================== 6 7This document describes the additional properties required by raw Netlink 8families such as ``NETLINK_ROUTE`` which use the ``netlink-raw`` protocol 9specification. 10 11Specification 12============= 13 14The netlink-raw schema extends the :doc:`genetlink-legacy <genetlink-legacy>` 15schema with properties that are needed to specify the protocol numbers and 16multicast IDs used by raw netlink families. See :ref:`classic_netlink` for more 17information. The raw netlink families also make use of type-specific 18sub-messages. 19 20Globals 21------- 22 23protonum 24~~~~~~~~ 25 26The ``protonum`` property is used to specify the protocol number to use when 27opening a netlink socket. 28 29.. code-block:: yaml 30 31 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) 32 33 name: rt-addr 34 protocol: netlink-raw 35 protonum: 0 # part of the NETLINK_ROUTE protocol 36 37 38Multicast group properties 39-------------------------- 40 41value 42~~~~~ 43 44The ``value`` property is used to specify the group ID to use for multicast 45group registration. 46 47.. code-block:: yaml 48 49 mcast-groups: 50 list: 51 - 52 name: rtnlgrp-ipv4-ifaddr 53 value: 5 54 - 55 name: rtnlgrp-ipv6-ifaddr 56 value: 9 57 - 58 name: rtnlgrp-mctp-ifaddr 59 value: 34 60 61Sub-messages 62------------ 63 64Several raw netlink families such as 65:doc:`rt_link<../../networking/netlink_spec/rt_link>` and 66:doc:`tc<../../networking/netlink_spec/tc>` use attribute nesting as an 67abstraction 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 or 80core TC), while specific drivers, TC classifiers, qdiscs etc. can carry their 81own information wrapped in the ``GENERIC ATTR - wrapper``. Even though the 82example above shows attributes nesting inside the wrapper, the modules generally 83have full freedom to define the format of the nest. In practice the payload of 84the wrapper attr has very similar characteristics to a netlink message. It may 85contain a fixed header / structure, netlink attributes, or both. Because of 86those shared characteristics we refer to the payload of the wrapper attribute as 87a sub-message. 88 89A sub-message attribute uses the value of another attribute as a selector key to 90choose the right sub-message format. For example if the following attribute has 91already been decoded: 92 93.. code-block:: json 94 95 { "kind": "gre" } 96 97and we encounter the following attribute spec: 98 99.. code-block:: yaml 100 101 - 102 name: data 103 type: sub-message 104 sub-message: linkinfo-data-msg 105 selector: kind 106 107Then we look for a sub-message definition called ``linkinfo-data-msg`` and use 108the value of the ``kind`` attribute i.e. ``gre`` as the key to choose the 109correct format for the sub-message: 110 111.. code-block:: yaml 112 113 sub-messages: 114 name: linkinfo-data-msg 115 formats: 116 - 117 value: bridge 118 attribute-set: linkinfo-bridge-attrs 119 - 120 value: gre 121 attribute-set: linkinfo-gre-attrs 122 - 123 value: geneve 124 attribute-set: linkinfo-geneve-attrs 125 126This would decode the attribute value as a sub-message with the attribute-set 127called ``linkinfo-gre-attrs`` as the attribute space. 128 129A sub-message can have an optional ``fixed-header`` followed by zero or more 130attributes from an ``attribute-set``. For example the following 131``tc-options-msg`` sub-message defines message formats that use a mixture of 132``fixed-header``, ``attribute-set`` or both together: 133 134.. code-block:: yaml 135 136 sub-messages: 137 - 138 name: tc-options-msg 139 formats: 140 - 141 value: bfifo 142 fixed-header: tc-fifo-qopt 143 - 144 value: cake 145 attribute-set: tc-cake-attrs 146 - 147 value: netem 148 fixed-header: tc-netem-qopt 149 attribute-set: tc-netem-attrs 150 151Note that a selector attribute must appear in a netlink message before any 152sub-message attributes that depend on it. 153 154If an attribute such as ``kind`` is defined at more than one nest level, then a 155sub-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``, then 158the selector will be resolved using the value 'closest' to the selector. If the 159value is not present in the message at the same level as defined in the spec 160then this is an error. 161 162Nested struct definitions 163------------------------- 164 165Many raw netlink families such as :doc:`tc<../../networking/netlink_spec/tc>` 166make use of nested struct definitions. The ``netlink-raw`` schema makes it 167possible to embed a struct within a struct definition using the ``struct`` 168property. For example, the following struct definition embeds the 169``tc-ratespec`` struct definition for both the ``rate`` and the ``peakrate`` 170members of ``struct tc-tbf-qopt``. 171 172.. code-block:: yaml 173 174 - 175 name: tc-tbf-qopt 176 type: struct 177 members: 178 - 179 name: rate 180 type: binary 181 struct: tc-ratespec 182 - 183 name: peakrate 184 type: binary 185 struct: tc-ratespec 186 - 187 name: limit 188 type: u32 189 - 190 name: buffer 191 type: u32 192 - 193 name: mtu 194 type: u32 195