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