1 .. SPDX-License-Identifier: BSD-3-Clause 1 .. SPDX-License-Identifier: BSD-3-Clause
2 2
3 ============================================== 3 =================================================================
4 Netlink specification support for legacy Gener 4 Netlink specification support for legacy Generic Netlink families
5 ============================================== 5 =================================================================
6 6
7 This document describes the many additional qu 7 This document describes the many additional quirks and properties
8 required to describe older Generic Netlink fam 8 required to describe older Generic Netlink families which form
9 the ``genetlink-legacy`` protocol level. 9 the ``genetlink-legacy`` protocol level.
10 10
11 Specification 11 Specification
12 ============= 12 =============
13 13
14 Globals 14 Globals
15 ------- 15 -------
16 16
17 Attributes listed directly at the root level o 17 Attributes listed directly at the root level of the spec file.
18 18
19 version 19 version
20 ~~~~~~~ 20 ~~~~~~~
21 21
22 Generic Netlink family version, default is 1. 22 Generic Netlink family version, default is 1.
23 23
24 ``version`` has historically been used to intr 24 ``version`` has historically been used to introduce family changes
25 which may break backwards compatibility. Since 25 which may break backwards compatibility. Since compatibility breaking changes
26 are generally not allowed ``version`` is very 26 are generally not allowed ``version`` is very rarely used.
27 27
28 Attribute type nests 28 Attribute type nests
29 -------------------- 29 --------------------
30 30
31 New Netlink families should use ``multi-attr`` 31 New Netlink families should use ``multi-attr`` to define arrays.
32 Older families (e.g. ``genetlink`` control fam 32 Older families (e.g. ``genetlink`` control family) attempted to
33 define array types reusing attribute type to c 33 define array types reusing attribute type to carry information.
34 34
35 For reference the ``multi-attr`` array may loo 35 For reference the ``multi-attr`` array may look like this::
36 36
37 [ARRAY-ATTR] 37 [ARRAY-ATTR]
38 [INDEX (optionally)] 38 [INDEX (optionally)]
39 [MEMBER1] 39 [MEMBER1]
40 [MEMBER2] 40 [MEMBER2]
41 [SOME-OTHER-ATTR] 41 [SOME-OTHER-ATTR]
42 [ARRAY-ATTR] 42 [ARRAY-ATTR]
43 [INDEX (optionally)] 43 [INDEX (optionally)]
44 [MEMBER1] 44 [MEMBER1]
45 [MEMBER2] 45 [MEMBER2]
46 46
47 where ``ARRAY-ATTR`` is the array entry type. 47 where ``ARRAY-ATTR`` is the array entry type.
48 48
49 indexed-array !! 49 array-nest
50 ~~~~~~~~~~~~~ !! 50 ~~~~~~~~~~
51 51
52 ``indexed-array`` wraps the entire array in an !! 52 ``array-nest`` creates the following structure::
53 limiting its size to 64kB). The ``ENTRY`` nest <<
54 index of the entry as their type instead of no <<
55 <<
56 A ``sub-type`` is needed to describe what type <<
57 ``sub-type`` means there are nest arrays in th <<
58 looks like:: <<
59 53
60 [SOME-OTHER-ATTR] 54 [SOME-OTHER-ATTR]
61 [ARRAY-ATTR] 55 [ARRAY-ATTR]
62 [ENTRY] 56 [ENTRY]
63 [MEMBER1] 57 [MEMBER1]
64 [MEMBER2] 58 [MEMBER2]
65 [ENTRY] 59 [ENTRY]
66 [MEMBER1] 60 [MEMBER1]
67 [MEMBER2] 61 [MEMBER2]
68 62
69 Other ``sub-type`` like ``u32`` means there is !! 63 It wraps the entire array in an extra attribute (hence limiting its size
70 in ``sub-type`` in the ``ENTRY``. The structur !! 64 to 64kB). The ``ENTRY`` nests are special and have the index of the entry
71 !! 65 as their type instead of normal attribute type.
72 [SOME-OTHER-ATTR] <<
73 [ARRAY-ATTR] <<
74 [ENTRY u32] <<
75 [ENTRY u32] <<
76 66
77 type-value 67 type-value
78 ~~~~~~~~~~ 68 ~~~~~~~~~~
79 69
80 ``type-value`` is a construct which uses attri 70 ``type-value`` is a construct which uses attribute types to carry
81 information about a single object (often used 71 information about a single object (often used when array is dumped
82 entry-by-entry). 72 entry-by-entry).
83 73
84 ``type-value`` can have multiple levels of nes 74 ``type-value`` can have multiple levels of nesting, for example
85 genetlink's policy dumps create the following 75 genetlink's policy dumps create the following structures::
86 76
87 [POLICY-IDX] 77 [POLICY-IDX]
88 [ATTR-IDX] 78 [ATTR-IDX]
89 [POLICY-INFO-ATTR1] 79 [POLICY-INFO-ATTR1]
90 [POLICY-INFO-ATTR2] 80 [POLICY-INFO-ATTR2]
91 81
92 Where the first level of nest has the policy i 82 Where the first level of nest has the policy index as it's attribute
93 type, it contains a single nest which has the 83 type, it contains a single nest which has the attribute index as its
94 type. Inside the attr-index nest are the polic 84 type. Inside the attr-index nest are the policy attributes. Modern
95 Netlink families should have instead defined t 85 Netlink families should have instead defined this as a flat structure,
96 the nesting serves no good purpose here. 86 the nesting serves no good purpose here.
97 87
98 Operations 88 Operations
99 ========== 89 ==========
100 90
101 Enum (message ID) model 91 Enum (message ID) model
102 ----------------------- 92 -----------------------
103 93
104 unified 94 unified
105 ~~~~~~~ 95 ~~~~~~~
106 96
107 Modern families use the ``unified`` message ID 97 Modern families use the ``unified`` message ID model, which uses
108 a single enumeration for all messages within f 98 a single enumeration for all messages within family. Requests and
109 responses share the same message ID. Notificat 99 responses share the same message ID. Notifications have separate
110 IDs from the same space. For example given the 100 IDs from the same space. For example given the following list
111 of operations: 101 of operations:
112 102
113 .. code-block:: yaml 103 .. code-block:: yaml
114 104
115 - 105 -
116 name: a 106 name: a
117 value: 1 107 value: 1
118 do: ... 108 do: ...
119 - 109 -
120 name: b 110 name: b
121 do: ... 111 do: ...
122 - 112 -
123 name: c 113 name: c
124 value: 4 114 value: 4
125 notify: a 115 notify: a
126 - 116 -
127 name: d 117 name: d
128 do: ... 118 do: ...
129 119
130 Requests and responses for operation ``a`` wil 120 Requests and responses for operation ``a`` will have the ID of 1,
131 the requests and responses of ``b`` - 2 (since 121 the requests and responses of ``b`` - 2 (since there is no explicit
132 ``value`` it's previous operation ``+ 1``). No 122 ``value`` it's previous operation ``+ 1``). Notification ``c`` will
133 use the ID of 4, operation ``d`` 5 etc. 123 use the ID of 4, operation ``d`` 5 etc.
134 124
135 directional 125 directional
136 ~~~~~~~~~~~ 126 ~~~~~~~~~~~
137 127
138 The ``directional`` model splits the ID assign 128 The ``directional`` model splits the ID assignment by the direction of
139 the message. Messages from and to the kernel c 129 the message. Messages from and to the kernel can't be confused with
140 each other so this conserves the ID space (at 130 each other so this conserves the ID space (at the cost of making
141 the programming more cumbersome). 131 the programming more cumbersome).
142 132
143 In this case ``value`` attribute should be spe 133 In this case ``value`` attribute should be specified in the ``request``
144 ``reply`` sections of the operations (if an op 134 ``reply`` sections of the operations (if an operation has both ``do``
145 and ``dump`` the IDs are shared, ``value`` sho 135 and ``dump`` the IDs are shared, ``value`` should be set in ``do``).
146 For notifications the ``value`` is provided at 136 For notifications the ``value`` is provided at the op level but it
147 only allocates a ``reply`` (i.e. a "from-kerne 137 only allocates a ``reply`` (i.e. a "from-kernel" ID). Let's look
148 at an example: 138 at an example:
149 139
150 .. code-block:: yaml 140 .. code-block:: yaml
151 141
152 - 142 -
153 name: a 143 name: a
154 do: 144 do:
155 request: 145 request:
156 value: 2 146 value: 2
157 attributes: ... 147 attributes: ...
158 reply: 148 reply:
159 value: 1 149 value: 1
160 attributes: ... 150 attributes: ...
161 - 151 -
162 name: b 152 name: b
163 notify: a 153 notify: a
164 - 154 -
165 name: c 155 name: c
166 notify: a 156 notify: a
167 value: 7 157 value: 7
168 - 158 -
169 name: d 159 name: d
170 do: ... 160 do: ...
171 161
172 In this case ``a`` will use 2 when sending the 162 In this case ``a`` will use 2 when sending the message to the kernel
173 and expects message with ID 1 in response. Not 163 and expects message with ID 1 in response. Notification ``b`` allocates
174 a "from-kernel" ID which is 2. ``c`` allocates 164 a "from-kernel" ID which is 2. ``c`` allocates "from-kernel" ID of 7.
175 If operation ``d`` does not set ``values`` exp 165 If operation ``d`` does not set ``values`` explicitly in the spec
176 it will be allocated 3 for the request (``a`` 166 it will be allocated 3 for the request (``a`` is the previous operation
177 with a request section and the value of 2) and 167 with a request section and the value of 2) and 8 for response (``c`` is
178 the previous operation in the "from-kernel" di 168 the previous operation in the "from-kernel" direction).
179 169
180 Other quirks 170 Other quirks
181 ============ 171 ============
182 172
183 Structures 173 Structures
184 ---------- 174 ----------
185 175
186 Legacy families can define C structures both t 176 Legacy families can define C structures both to be used as the contents of
187 an attribute and as a fixed message header. St 177 an attribute and as a fixed message header. Structures are defined in
188 ``definitions`` and referenced in operations 178 ``definitions`` and referenced in operations or attributes.
189 179
190 members 180 members
191 ~~~~~~~ 181 ~~~~~~~
192 182
193 - ``name`` - The attribute name of the struct 183 - ``name`` - The attribute name of the struct member
194 - ``type`` - One of the scalar types ``u8``, 184 - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``,
195 ``s16``, ``s32``, ``s64``, ``string``, ``bi 185 ``s16``, ``s32``, ``s64``, ``string``, ``binary`` or ``bitfield32``.
196 - ``byte-order`` - ``big-endian`` or ``little 186 - ``byte-order`` - ``big-endian`` or ``little-endian``
197 - ``doc``, ``enum``, ``enum-as-flags``, ``dis 187 - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for
198 :ref:`attribute definitions <attribute_prop 188 :ref:`attribute definitions <attribute_properties>`
199 189
200 Note that structures defined in YAML are impli 190 Note that structures defined in YAML are implicitly packed according to C
201 conventions. For example, the following struct 191 conventions. For example, the following struct is 4 bytes, not 6 bytes:
202 192
203 .. code-block:: c 193 .. code-block:: c
204 194
205 struct { 195 struct {
206 u8 a; 196 u8 a;
207 u16 b; 197 u16 b;
208 u8 c; 198 u8 c;
209 } 199 }
210 200
211 Any padding must be explicitly added and C-lik 201 Any padding must be explicitly added and C-like languages should infer the
212 need for explicit padding from whether the mem 202 need for explicit padding from whether the members are naturally aligned.
213 203
214 Here is the struct definition from above, decl 204 Here is the struct definition from above, declared in YAML:
215 205
216 .. code-block:: yaml 206 .. code-block:: yaml
217 207
218 definitions: 208 definitions:
219 - 209 -
220 name: message-header 210 name: message-header
221 type: struct 211 type: struct
222 members: 212 members:
223 - 213 -
224 name: a 214 name: a
225 type: u8 215 type: u8
226 - 216 -
227 name: b 217 name: b
228 type: u16 218 type: u16
229 - 219 -
230 name: c 220 name: c
231 type: u8 221 type: u8
232 222
233 Fixed Headers 223 Fixed Headers
234 ~~~~~~~~~~~~~ 224 ~~~~~~~~~~~~~
235 225
236 Fixed message headers can be added to operatio 226 Fixed message headers can be added to operations using ``fixed-header``.
237 The default ``fixed-header`` can be set in ``o 227 The default ``fixed-header`` can be set in ``operations`` and it can be set
238 or overridden for each operation. 228 or overridden for each operation.
239 229
240 .. code-block:: yaml 230 .. code-block:: yaml
241 231
242 operations: 232 operations:
243 fixed-header: message-header 233 fixed-header: message-header
244 list: 234 list:
245 - 235 -
246 name: get 236 name: get
247 fixed-header: custom-header 237 fixed-header: custom-header
248 attribute-set: message-attrs 238 attribute-set: message-attrs
249 239
250 Attributes 240 Attributes
251 ~~~~~~~~~~ 241 ~~~~~~~~~~
252 242
253 A ``binary`` attribute can be interpreted as a 243 A ``binary`` attribute can be interpreted as a C structure using a
254 ``struct`` property with the name of the struc 244 ``struct`` property with the name of the structure definition. The
255 ``struct`` property implies ``sub-type: struct 245 ``struct`` property implies ``sub-type: struct`` so it is not necessary to
256 specify a sub-type. 246 specify a sub-type.
257 247
258 .. code-block:: yaml 248 .. code-block:: yaml
259 249
260 attribute-sets: 250 attribute-sets:
261 - 251 -
262 name: stats-attrs 252 name: stats-attrs
263 attributes: 253 attributes:
264 - 254 -
265 name: stats 255 name: stats
266 type: binary 256 type: binary
267 struct: vport-stats 257 struct: vport-stats
268 258
269 C Arrays 259 C Arrays
270 -------- 260 --------
271 261
272 Legacy families also use ``binary`` attributes 262 Legacy families also use ``binary`` attributes to encapsulate C arrays. The
273 ``sub-type`` is used to identify the type of s 263 ``sub-type`` is used to identify the type of scalar to extract.
274 264
275 .. code-block:: yaml 265 .. code-block:: yaml
276 266
277 attributes: 267 attributes:
278 - 268 -
279 name: ports 269 name: ports
280 type: binary 270 type: binary
281 sub-type: u32 271 sub-type: u32
282 272
283 Multi-message DO 273 Multi-message DO
284 ---------------- 274 ----------------
285 275
286 New Netlink families should never respond to a 276 New Netlink families should never respond to a DO operation with multiple
287 replies, with ``NLM_F_MULTI`` set. Use a filte 277 replies, with ``NLM_F_MULTI`` set. Use a filtered dump instead.
288 278
289 At the spec level we can define a ``dumps`` pr 279 At the spec level we can define a ``dumps`` property for the ``do``,
290 perhaps with values of ``combine`` and ``multi 280 perhaps with values of ``combine`` and ``multi-object`` depending
291 on how the parsing should be implemented (pars 281 on how the parsing should be implemented (parse into a single reply
292 vs list of objects i.e. pretty much a dump). 282 vs list of objects i.e. pretty much a dump).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.