1 .. SPDX-License-Identifier: BSD-3-Clause
2
3 ==============================================
4 Netlink specification support for raw Netlink
5 ==============================================
6
7 This document describes the additional propert
8 families such as ``NETLINK_ROUTE`` which use t
9 specification.
10
11 Specification
12 =============
13
14 The netlink-raw schema extends the :doc:`genet
15 schema with properties that are needed to spec
16 multicast IDs used by raw netlink families. Se
17 information. The raw netlink families also mak
18 sub-messages.
19
20 Globals
21 -------
22
23 protonum
24 ~~~~~~~~
25
26 The ``protonum`` property is used to specify t
27 opening a netlink socket.
28
29 .. code-block:: yaml
30
31 # SPDX-License-Identifier: ((GPL-2.0 WITH Li
32
33 name: rt-addr
34 protocol: netlink-raw
35 protonum: 0 # part of the NETLIN
36
37
38 Multicast group properties
39 --------------------------
40
41 value
42 ~~~~~
43
44 The ``value`` property is used to specify the
45 group 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
61 Sub-messages
62 ------------
63
64 Several raw netlink families such as
65 :doc:`rt_link<../../networking/netlink_spec/rt
66 :doc:`tc<../../networking/netlink_spec/tc>` us
67 abstraction to carry module specific informati
68
69 Conceptually 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
79 The ``GENERIC ATTRs`` at the outer level are d
80 core TC), while specific drivers, TC classifie
81 own information wrapped in the ``GENERIC ATTR
82 example above shows attributes nesting inside
83 have full freedom to define the format of the
84 the wrapper attr has very similar characterist
85 contain a fixed header / structure, netlink at
86 those shared characteristics we refer to the p
87 a sub-message.
88
89 A sub-message attribute uses the value of anot
90 choose the right sub-message format. For examp
91 already been decoded:
92
93 .. code-block:: json
94
95 { "kind": "gre" }
96
97 and 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
107 Then we look for a sub-message definition call
108 the value of the ``kind`` attribute i.e. ``gre
109 correct 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
126 This would decode the attribute value as a sub
127 called ``linkinfo-gre-attrs`` as the attribute
128
129 A sub-message can have an optional ``fixed-hea
130 attributes from an ``attribute-set``. For exam
131 ``tc-options-msg`` sub-message defines message
132 ``fixed-header``, ``attribute-set`` or both to
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
151 Note that a selector attribute must appear in
152 sub-message attributes that depend on it.
153
154 If an attribute such as ``kind`` is defined at
155 sub-message selector will be resolved using th
156 For example, if the same attribute name is def
157 alongside a sub-message selector and also in a
158 the selector will be resolved using the value
159 value is not present in the message at the sam
160 then this is an error.
161
162 Nested struct definitions
163 -------------------------
164
165 Many raw netlink families such as :doc:`tc<../
166 make use of nested struct definitions. The ``n
167 possible to embed a struct within a struct def
168 property. For example, the following struct de
169 ``tc-ratespec`` struct definition for both the
170 members 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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.