1 .. SPDX-License-Identifier: BSD-3-Clause
2
3 =========================================
4 Netlink protocol specifications (in YAML)
5 =========================================
6
7 Netlink protocol specifications are complete,
8 Netlink protocols written in YAML. The goal of
9 separating Netlink parsing from user space log
10 hand written Netlink code for each new family,
11 Netlink specs should be complete and not depen
12 or C header file, making it easy to use in lan
13 kernel headers directly.
14
15 Internally kernel uses the YAML specs to gener
16
17 - the C uAPI header
18 - documentation of the protocol as a ReST fil
19 - policy tables for input attribute validatio
20 - operation tables
21
22 YAML specifications can be found under ``Docum
23
24 This document describes details of the schema.
25 See :doc:`intro-specs` for a practical startin
26
27 All specs must be licensed under
28 ``((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-
29 to allow for easy adoption in user space code.
30
31 Compatibility levels
32 ====================
33
34 There are four schema levels for Netlink specs
35 by new families to the most complex covering a
36 Each next level inherits the attributes of the
37 user capable of parsing more complex ``genetli
38 with simpler ones. The levels are:
39
40 - ``genetlink`` - most streamlined, should be
41 - ``genetlink-c`` - superset of ``genetlink``
42 customization of define and enum type and v
43 be equivalent to ``genetlink`` for all impl
44 directly with C uAPI headers
45 - ``genetlink-legacy`` - Generic Netlink catc
46 all old genetlink families, strange attribu
47 - ``netlink-raw`` - catch all schema supporti
48 such as ``NETLINK_ROUTE``
49
50 The definition of the schemas (in ``jsonschema
51 under ``Documentation/netlink/``.
52
53 Schema structure
54 ================
55
56 YAML schema has the following conceptual secti
57
58 - globals
59 - definitions
60 - attributes
61 - operations
62 - multicast groups
63
64 Most properties in the schema accept (or in fa
65 sub-property documenting the defined object.
66
67 The following sections describe the properties
68 schema. See the documentation of :doc:`genetli
69 for information on how C names are derived fro
70
71 See also :ref:`Documentation/core-api/netlink.
72 information on the Netlink specification prope
73 the kernel space and not part of the user spac
74
75 genetlink
76 =========
77
78 Globals
79 -------
80
81 Attributes listed directly at the root level o
82
83 name
84 ~~~~
85
86 Name of the family. Name identifies the family
87 the Family IDs are allocated dynamically.
88
89 protocol
90 ~~~~~~~~
91
92 The schema level, default is ``genetlink``, wh
93 allowed for new ``genetlink`` families.
94
95 definitions
96 -----------
97
98 Array of type and constant definitions.
99
100 name
101 ~~~~
102
103 Name of the type / constant.
104
105 type
106 ~~~~
107
108 One of the following types:
109
110 - const - a single, standalone constant
111 - enum - defines an integer enumeration, with
112 incrementing by 1, (e.g. 0, 1, 2, 3)
113 - flags - defines an integer enumeration, wit
114 occupying a bit, starting from bit 0, (e.g.
115
116 value
117 ~~~~~
118
119 The value for the ``const``.
120
121 value-start
122 ~~~~~~~~~~~
123
124 The first value for ``enum`` and ``flags``, al
125 start value of ``0`` (for ``enum``) and starti
126 For ``flags`` ``value-start`` selects the star
127
128 Sparse enumerations are not supported.
129
130 entries
131 ~~~~~~~
132
133 Array of names of the entries for ``enum`` and
134
135 header
136 ~~~~~~
137
138 For C-compatible languages, header which alrea
139 In case the definition is shared by multiple f
140 code generators for C-compatible languages may
141 include instead of rendering a new definition.
142
143 attribute-sets
144 --------------
145
146 This property contains information about netli
147 All families have at least one attribute set,
148 ``attribute-sets`` is an array, with each entr
149
150 Note that the spec is "flattened" and is not m
151 the format of the netlink messages (unlike cer
152 formats seen in kernel comments). In the spec
153 are not defined inline as a nest, but defined
154 referred to with a ``nested-attributes`` prope
155
156 Spec may also contain fractional sets - sets w
157 property. Such sets describe a section of a fu
158 which attributes are allowed in a nest or refi
159 Fractional sets can only be used in nests. The
160 in any fashion.
161
162 name
163 ~~~~
164
165 Uniquely identifies the attribute set, operati
166 refer to the sets by the ``name``.
167
168 subset-of
169 ~~~~~~~~~
170
171 Re-defines a portion of another set (a fractio
172 Allows narrowing down fields and changing vali
173 or even types of attributes depending on the n
174 are contained. The ``value`` of each attribute
175 set is implicitly the same as in the main set.
176
177 attributes
178 ~~~~~~~~~~
179
180 List of attributes in the set.
181
182 .. _attribute_properties:
183
184 Attribute properties
185 --------------------
186
187 name
188 ~~~~
189
190 Identifies the attribute, unique within the se
191
192 type
193 ~~~~
194
195 Netlink attribute type, see :ref:`attr_types`.
196
197 .. _assign_val:
198
199 value
200 ~~~~~
201
202 Numerical attribute ID, used in serialized Net
203 The ``value`` property can be skipped, in whic
204 will be the value of the previous attribute pl
205 and ``1`` for the first attribute in the attri
206
207 Attributes (and operations) use ``1`` as the d
208 entry (unlike enums in definitions which start
209 entry ``0`` is almost always reserved as undef
210 set value to ``0`` if needed.
211
212 Note that the ``value`` of an attribute is def
213 (not in subsets).
214
215 enum
216 ~~~~
217
218 For integer types specifies that values in the
219 to an ``enum`` or ``flags`` from the ``definit
220
221 enum-as-flags
222 ~~~~~~~~~~~~~
223
224 Treat ``enum`` as ``flags`` regardless of its
225 When both ``enum`` and ``flags`` forms are nee
226 contain an ``enum`` and attributes which need
227 use this attribute.
228
229 nested-attributes
230 ~~~~~~~~~~~~~~~~~
231
232 Identifies the attribute space for attributes
233 Only valid for complex attributes which may ha
234
235 multi-attr (arrays)
236 ~~~~~~~~~~~~~~~~~~~
237
238 Boolean property signifying that the attribute
239 Allowing an attribute to repeat is the recomme
240 (no extra nesting).
241
242 byte-order
243 ~~~~~~~~~~
244
245 For integer types specifies attribute byte ord
246 or ``big-endian``.
247
248 checks
249 ~~~~~~
250
251 Input validation constraints used by the kerne
252 the policy of the running kernel using Generic
253 rather than depend on what is specified in the
254
255 The validation policy in the kernel is formed
256 definition (``type`` and ``nested-attributes``
257
258 sub-type
259 ~~~~~~~~
260
261 Legacy families have special ways of expressin
262 used to define the type of array members in ca
263 fully defined as attributes (in a bona fide at
264 a C array of u32 values can be specified with
265 ``sub-type: u32``. Binary types and legacy arr
266 more detail in :doc:`genetlink-legacy`.
267
268 display-hint
269 ~~~~~~~~~~~~
270
271 Optional format indicator that is intended onl
272 formatting mechanism when displaying values of
273 hints are ``hex``, ``mac``, ``fddi``, ``ipv4``
274
275 operations
276 ----------
277
278 This section describes messages passed between
279 There are three types of entries in this secti
280 and events.
281
282 Operations describe the most common request -
283 sends a request and kernel replies. Each opera
284 of the two modes familiar to netlink users - `
285 ``do`` and ``dump`` in turn contain a combinat
286 ``response`` properties. If no explicit messag
287 in a given direction (e.g. a ``dump`` which do
288 of a SET operation to which the kernel respond
289 code) ``request`` or ``response`` section can
290 ``request`` and ``response`` sections list the
291 The list contains only the names of attributes
292 to by the ``attribute-set`` property.
293
294 Notifications and events both refer to the asy
295 the kernel to members of a multicast group. Th
296 two is that a notification shares its contents
297 (the name of the GET operation is specified in
298 This arrangement is commonly used for notifica
299 objects where the notification carries the ful
300
301 Events are more focused and carry only a subse
302 object state (a made up example would be a lin
303 the interface name and the new link state). Ev
304 property. Events are considered less idiomatic
305 should be preferred.
306
307 list
308 ~~~~
309
310 The only property of ``operations`` for ``gene
311 operations, notifications etc.
312
313 Operation properties
314 --------------------
315
316 name
317 ~~~~
318
319 Identifies the operation.
320
321 value
322 ~~~~~
323
324 Numerical message ID, used in serialized Netli
325 The same enumeration rules are applied as to
326 :ref:`attribute values<assign_val>`.
327
328 attribute-set
329 ~~~~~~~~~~~~~
330
331 Specifies the attribute set contained within t
332
333 do
334 ~~~
335
336 Specification for the ``doit`` request. Should
337 or both of these properties, each holding a :r
338
339 dump
340 ~~~~
341
342 Specification for the ``dumpit`` request. Shou
343 or both of these properties, each holding a :r
344
345 notify
346 ~~~~~~
347
348 Designates the message as a notification. Cont
349 (possibly the same as the operation holding th
350 the contents with the notification (``do``).
351
352 event
353 ~~~~~
354
355 Specification of attributes in the event, hold
356 ``event`` property is mutually exclusive with
357
358 mcgrp
359 ~~~~~
360
361 Used with ``event`` and ``notify``, specifies
362 message belongs to.
363
364 .. _attr_list:
365
366 Message attribute list
367 ----------------------
368
369 ``request``, ``reply`` and ``event`` propertie
370 property which holds the list of attribute nam
371
372 Messages can also define ``pre`` and ``post``
373 as ``pre_doit`` and ``post_doit`` calls in the
374 be ignored by user space).
375
376 mcast-groups
377 ------------
378
379 This section lists the multicast groups of the
380
381 list
382 ~~~~
383
384 The only property of ``mcast-groups`` for ``ge
385 of groups.
386
387 Multicast group properties
388 --------------------------
389
390 name
391 ~~~~
392
393 Uniquely identifies the multicast group in the
394 Family ID, Multicast Group ID needs to be reso
395 on the name.
396
397 .. _attr_types:
398
399 Attribute types
400 ===============
401
402 This section describes the attribute types sup
403 compatibility level. Refer to documentation of
404 attribute types.
405
406 Common integer types
407 --------------------
408
409 ``sint`` and ``uint`` represent signed and uns
410 If the value can fit on 32 bits only 32 bits a
411 messages, otherwise full 64 bits are carried.
412 is only aligned to 4B, so the full 64 bit valu
413
414 Common integer types should be preferred over
415 of cases.
416
417 Fix-width integer types
418 -----------------------
419
420 Fixed-width integer types include:
421 ``u8``, ``u16``, ``u32``, ``u64``, ``s8``, ``s
422
423 Note that types smaller than 32 bit should be
424 does not save any memory in Netlink messages (
425 See :ref:`pad_type` for padding of 64 bit attr
426
427 The payload of the attribute is the integer in
428 specifies otherwise.
429
430 64 bit values are usually aligned by the kerne
431 that the user space is able to deal with unali
432
433 .. _pad_type:
434
435 pad
436 ---
437
438 Special attribute type used for padding attrib
439 bigger than standard 4B alignment required by
440 There can only be a single attribute of the ``
441 and it should be automatically used for paddin
442
443 flag
444 ----
445
446 Attribute with no payload, its presence is the
447
448 binary
449 ------
450
451 Raw binary data attribute, the contents are op
452
453 string
454 ------
455
456 Character string. Unless ``checks`` has ``unte
457 the string is required to be null terminated.
458 ``max-len`` in ``checks`` indicates the longes
459 if not present the length of the string is unb
460
461 Note that ``max-len`` does not count the termi
462
463 nest
464 ----
465
466 Attribute containing other (nested) attributes
467 ``nested-attributes`` specifies which attribut
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.