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