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