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