1 .. SPDX-License-Identifier: BSD-3-Clause
2
3 ==============================================
4 Netlink specification support for legacy Gener
5 ==============================================
6
7 This document describes the many additional qu
8 required to describe older Generic Netlink fam
9 the ``genetlink-legacy`` protocol level.
10
11 Specification
12 =============
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
29 --------------------
30
31 New Netlink families should use ``multi-attr``
32 Older families (e.g. ``genetlink`` control fam
33 define array types reusing attribute type to c
34
35 For reference the ``multi-attr`` array may loo
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
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
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
70 in ``sub-type`` in the ``ENTRY``. The structur
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 attri
81 information about a single object (often used
82 entry-by-entry).
83
84 ``type-value`` can have multiple levels of nes
85 genetlink's policy dumps create the following
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 i
93 type, it contains a single nest which has the
94 type. Inside the attr-index nest are the polic
95 Netlink families should have instead defined t
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
108 a single enumeration for all messages within f
109 responses share the same message ID. Notificat
110 IDs from the same space. For example given the
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`` wil
131 the requests and responses of ``b`` - 2 (since
132 ``value`` it's previous operation ``+ 1``). No
133 use the ID of 4, operation ``d`` 5 etc.
134
135 directional
136 ~~~~~~~~~~~
137
138 The ``directional`` model splits the ID assign
139 the message. Messages from and to the kernel c
140 each other so this conserves the ID space (at
141 the programming more cumbersome).
142
143 In this case ``value`` attribute should be spe
144 ``reply`` sections of the operations (if an op
145 and ``dump`` the IDs are shared, ``value`` sho
146 For notifications the ``value`` is provided at
147 only allocates a ``reply`` (i.e. a "from-kerne
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
173 and expects message with ID 1 in response. Not
174 a "from-kernel" ID which is 2. ``c`` allocates
175 If operation ``d`` does not set ``values`` exp
176 it will be allocated 3 for the request (``a``
177 with a request section and the value of 2) and
178 the previous operation in the "from-kernel" di
179
180 Other quirks
181 ============
182
183 Structures
184 ----------
185
186 Legacy families can define C structures both t
187 an attribute and as a fixed message header. St
188 ``definitions`` and referenced in operations
189
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
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-lik
212 need for explicit padding from whether the mem
213
214 Here is the struct definition from above, decl
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 operatio
237 The default ``fixed-header`` can be set in ``o
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
254 ``struct`` property with the name of the struc
255 ``struct`` property implies ``sub-type: struct
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
273 ``sub-type`` is used to identify the type of s
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
287 replies, with ``NLM_F_MULTI`` set. Use a filte
288
289 At the spec level we can define a ``dumps`` pr
290 perhaps with values of ``combine`` and ``multi
291 on how the parsing should be implemented (pars
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.