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