Commit | Line | Data |
---|---|---|
9d6a6507 JK |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | ||
3 | ========================================= | |
4 | Netlink protocol specifications (in YAML) | |
5 | ========================================= | |
6 | ||
7 | Netlink protocol specifications are complete, machine readable descriptions of | |
8 | Netlink protocols written in YAML. The goal of the specifications is to allow | |
9 | separating Netlink parsing from user space logic and minimize the amount of | |
10 | hand written Netlink code for each new family, command, attribute. | |
11 | Netlink specs should be complete and not depend on any other spec | |
12 | or C header file, making it easy to use in languages which can't include | |
13 | kernel headers directly. | |
14 | ||
15 | Internally kernel uses the YAML specs to generate: | |
16 | ||
17 | - the C uAPI header | |
18 | - documentation of the protocol as a ReST file | |
19 | - policy tables for input attribute validation | |
20 | - operation tables | |
21 | ||
22 | YAML specifications can be found under ``Documentation/netlink/specs/`` | |
23 | ||
01e47a37 JK |
24 | This document describes details of the schema. |
25 | See :doc:`intro-specs` for a practical starting guide. | |
26 | ||
9d6a6507 JK |
27 | Compatibility levels |
28 | ==================== | |
29 | ||
30 | There are four schema levels for Netlink specs, from the simplest used | |
31 | by new families to the most complex covering all the quirks of the old ones. | |
32 | Each next level inherits the attributes of the previous level, meaning that | |
33 | user capable of parsing more complex ``genetlink`` schemas is also compatible | |
34 | with simpler ones. The levels are: | |
35 | ||
36 | - ``genetlink`` - most streamlined, should be used by all new families | |
37 | - ``genetlink-c`` - superset of ``genetlink`` with extra attributes allowing | |
38 | customization of define and enum type and value names; this schema should | |
39 | be equivalent to ``genetlink`` for all implementations which don't interact | |
40 | directly with C uAPI headers | |
41 | - ``genetlink-legacy`` - Generic Netlink catch all schema supporting quirks of | |
42 | all old genetlink families, strange attribute formats, binary structures etc. | |
43 | - ``netlink-raw`` - catch all schema supporting pre-Generic Netlink protocols | |
44 | such as ``NETLINK_ROUTE`` | |
45 | ||
46 | The definition of the schemas (in ``jsonschema``) can be found | |
47 | under ``Documentation/netlink/``. | |
48 | ||
49 | Schema structure | |
50 | ================ | |
51 | ||
52 | YAML schema has the following conceptual sections: | |
53 | ||
54 | - globals | |
55 | - definitions | |
56 | - attributes | |
57 | - operations | |
58 | - multicast groups | |
59 | ||
60 | Most properties in the schema accept (or in fact require) a ``doc`` | |
61 | sub-property documenting the defined object. | |
62 | ||
63 | The following sections describe the properties of the most modern ``genetlink`` | |
64 | schema. See the documentation of :doc:`genetlink-c <c-code-gen>` | |
65 | for information on how C names are derived from name properties. | |
66 | ||
67 | genetlink | |
68 | ========= | |
69 | ||
70 | Globals | |
71 | ------- | |
72 | ||
73 | Attributes listed directly at the root level of the spec file. | |
74 | ||
75 | name | |
76 | ~~~~ | |
77 | ||
78 | Name of the family. Name identifies the family in a unique way, since | |
79 | the Family IDs are allocated dynamically. | |
80 | ||
81 | version | |
82 | ~~~~~~~ | |
83 | ||
84 | Generic Netlink family version, default is 1. | |
85 | ||
86 | protocol | |
87 | ~~~~~~~~ | |
88 | ||
89 | The schema level, default is ``genetlink``, which is the only value | |
90 | allowed for new ``genetlink`` families. | |
91 | ||
92 | definitions | |
93 | ----------- | |
94 | ||
95 | Array of type and constant definitions. | |
96 | ||
97 | name | |
98 | ~~~~ | |
99 | ||
100 | Name of the type / constant. | |
101 | ||
102 | type | |
103 | ~~~~ | |
104 | ||
105 | One of the following types: | |
106 | ||
107 | - const - a single, standalone constant | |
108 | - enum - defines an integer enumeration, with values for each entry | |
109 | incrementing by 1, (e.g. 0, 1, 2, 3) | |
110 | - flags - defines an integer enumeration, with values for each entry | |
111 | occupying a bit, starting from bit 0, (e.g. 1, 2, 4, 8) | |
112 | ||
113 | value | |
114 | ~~~~~ | |
115 | ||
116 | The value for the ``const``. | |
117 | ||
118 | value-start | |
119 | ~~~~~~~~~~~ | |
120 | ||
121 | The first value for ``enum`` and ``flags``, allows overriding the default | |
122 | start value of ``0`` (for ``enum``) and starting bit (for ``flags``). | |
123 | For ``flags`` ``value-start`` selects the starting bit, not the shifted value. | |
124 | ||
125 | Sparse enumerations are not supported. | |
126 | ||
127 | entries | |
128 | ~~~~~~~ | |
129 | ||
130 | Array of names of the entries for ``enum`` and ``flags``. | |
131 | ||
132 | header | |
133 | ~~~~~~ | |
134 | ||
135 | For C-compatible languages, header which already defines this value. | |
136 | In case the definition is shared by multiple families (e.g. ``IFNAMSIZ``) | |
137 | code generators for C-compatible languages may prefer to add an appropriate | |
138 | include instead of rendering a new definition. | |
139 | ||
140 | attribute-sets | |
141 | -------------- | |
142 | ||
143 | This property contains information about netlink attributes of the family. | |
144 | All families have at least one attribute set, most have multiple. | |
145 | ``attribute-sets`` is an array, with each entry describing a single set. | |
146 | ||
147 | Note that the spec is "flattened" and is not meant to visually resemble | |
148 | the format of the netlink messages (unlike certain ad-hoc documentation | |
149 | formats seen in kernel comments). In the spec subordinate attribute sets | |
150 | are not defined inline as a nest, but defined in a separate attribute set | |
151 | referred to with a ``nested-attributes`` property of the container. | |
152 | ||
153 | Spec may also contain fractional sets - sets which contain a ``subset-of`` | |
154 | property. Such sets describe a section of a full set, allowing narrowing down | |
155 | which attributes are allowed in a nest or refining the validation criteria. | |
156 | Fractional sets can only be used in nests. They are not rendered to the uAPI | |
157 | in any fashion. | |
158 | ||
159 | name | |
160 | ~~~~ | |
161 | ||
162 | Uniquely identifies the attribute set, operations and nested attributes | |
163 | refer to the sets by the ``name``. | |
164 | ||
165 | subset-of | |
166 | ~~~~~~~~~ | |
167 | ||
168 | Re-defines a portion of another set (a fractional set). | |
169 | Allows narrowing down fields and changing validation criteria | |
170 | or even types of attributes depending on the nest in which they | |
171 | are contained. The ``value`` of each attribute in the fractional | |
172 | set is implicitly the same as in the main set. | |
173 | ||
174 | attributes | |
175 | ~~~~~~~~~~ | |
176 | ||
177 | List of attributes in the set. | |
178 | ||
179 | Attribute properties | |
180 | -------------------- | |
181 | ||
182 | name | |
183 | ~~~~ | |
184 | ||
185 | Identifies the attribute, unique within the set. | |
186 | ||
187 | type | |
188 | ~~~~ | |
189 | ||
190 | Netlink attribute type, see :ref:`attr_types`. | |
191 | ||
192 | .. _assign_val: | |
193 | ||
194 | value | |
195 | ~~~~~ | |
196 | ||
197 | Numerical attribute ID, used in serialized Netlink messages. | |
198 | The ``value`` property can be skipped, in which case the attribute ID | |
199 | will be the value of the previous attribute plus one (recursively) | |
200 | and ``0`` for the first attribute in the attribute set. | |
201 | ||
7cf93538 JK |
202 | Note that the ``value`` of an attribute is defined only in its main set |
203 | (not in subsets). | |
9d6a6507 JK |
204 | |
205 | enum | |
206 | ~~~~ | |
207 | ||
208 | For integer types specifies that values in the attribute belong | |
209 | to an ``enum`` or ``flags`` from the ``definitions`` section. | |
210 | ||
211 | enum-as-flags | |
212 | ~~~~~~~~~~~~~ | |
213 | ||
214 | Treat ``enum`` as ``flags`` regardless of its type in ``definitions``. | |
215 | When both ``enum`` and ``flags`` forms are needed ``definitions`` should | |
216 | contain an ``enum`` and attributes which need the ``flags`` form should | |
217 | use this attribute. | |
218 | ||
219 | nested-attributes | |
220 | ~~~~~~~~~~~~~~~~~ | |
221 | ||
222 | Identifies the attribute space for attributes nested within given attribute. | |
223 | Only valid for complex attributes which may have sub-attributes. | |
224 | ||
225 | multi-attr (arrays) | |
226 | ~~~~~~~~~~~~~~~~~~~ | |
227 | ||
228 | Boolean property signifying that the attribute may be present multiple times. | |
229 | Allowing an attribute to repeat is the recommended way of implementing arrays | |
230 | (no extra nesting). | |
231 | ||
232 | byte-order | |
233 | ~~~~~~~~~~ | |
234 | ||
235 | For integer types specifies attribute byte order - ``little-endian`` | |
236 | or ``big-endian``. | |
237 | ||
238 | checks | |
239 | ~~~~~~ | |
240 | ||
241 | Input validation constraints used by the kernel. User space should query | |
242 | the policy of the running kernel using Generic Netlink introspection, | |
243 | rather than depend on what is specified in the spec file. | |
244 | ||
245 | The validation policy in the kernel is formed by combining the type | |
246 | definition (``type`` and ``nested-attributes``) and the ``checks``. | |
247 | ||
248 | operations | |
249 | ---------- | |
250 | ||
251 | This section describes messages passed between the kernel and the user space. | |
252 | There are three types of entries in this section - operations, notifications | |
253 | and events. | |
254 | ||
255 | Operations describe the most common request - response communication. User | |
256 | sends a request and kernel replies. Each operation may contain any combination | |
257 | of the two modes familiar to netlink users - ``do`` and ``dump``. | |
258 | ``do`` and ``dump`` in turn contain a combination of ``request`` and | |
259 | ``response`` properties. If no explicit message with attributes is passed | |
260 | in a given direction (e.g. a ``dump`` which does not accept filter, or a ``do`` | |
261 | of a SET operation to which the kernel responds with just the netlink error | |
262 | code) ``request`` or ``response`` section can be skipped. | |
263 | ``request`` and ``response`` sections list the attributes allowed in a message. | |
264 | The list contains only the names of attributes from a set referred | |
265 | to by the ``attribute-set`` property. | |
266 | ||
267 | Notifications and events both refer to the asynchronous messages sent by | |
268 | the kernel to members of a multicast group. The difference between the | |
269 | two is that a notification shares its contents with a GET operation | |
270 | (the name of the GET operation is specified in the ``notify`` property). | |
271 | This arrangement is commonly used for notifications about | |
272 | objects where the notification carries the full object definition. | |
273 | ||
274 | Events are more focused and carry only a subset of information rather than full | |
275 | object state (a made up example would be a link state change event with just | |
276 | the interface name and the new link state). Events contain the ``event`` | |
277 | property. Events are considered less idiomatic for netlink and notifications | |
278 | should be preferred. | |
279 | ||
280 | list | |
281 | ~~~~ | |
282 | ||
283 | The only property of ``operations`` for ``genetlink``, holds the list of | |
284 | operations, notifications etc. | |
285 | ||
286 | Operation properties | |
287 | -------------------- | |
288 | ||
289 | name | |
290 | ~~~~ | |
291 | ||
292 | Identifies the operation. | |
293 | ||
294 | value | |
295 | ~~~~~ | |
296 | ||
297 | Numerical message ID, used in serialized Netlink messages. | |
298 | The same enumeration rules are applied as to | |
299 | :ref:`attribute values<assign_val>`. | |
300 | ||
301 | attribute-set | |
302 | ~~~~~~~~~~~~~ | |
303 | ||
304 | Specifies the attribute set contained within the message. | |
305 | ||
306 | do | |
307 | ~~~ | |
308 | ||
309 | Specification for the ``doit`` request. Should contain ``request``, ``reply`` | |
310 | or both of these properties, each holding a :ref:`attr_list`. | |
311 | ||
312 | dump | |
313 | ~~~~ | |
314 | ||
315 | Specification for the ``dumpit`` request. Should contain ``request``, ``reply`` | |
316 | or both of these properties, each holding a :ref:`attr_list`. | |
317 | ||
318 | notify | |
319 | ~~~~~~ | |
320 | ||
321 | Designates the message as a notification. Contains the name of the operation | |
322 | (possibly the same as the operation holding this property) which shares | |
323 | the contents with the notification (``do``). | |
324 | ||
325 | event | |
326 | ~~~~~ | |
327 | ||
328 | Specification of attributes in the event, holds a :ref:`attr_list`. | |
329 | ``event`` property is mutually exclusive with ``notify``. | |
330 | ||
331 | mcgrp | |
332 | ~~~~~ | |
333 | ||
334 | Used with ``event`` and ``notify``, specifies which multicast group | |
335 | message belongs to. | |
336 | ||
337 | .. _attr_list: | |
338 | ||
339 | Message attribute list | |
340 | ---------------------- | |
341 | ||
342 | ``request``, ``reply`` and ``event`` properties have a single ``attributes`` | |
343 | property which holds the list of attribute names. | |
344 | ||
345 | Messages can also define ``pre`` and ``post`` properties which will be rendered | |
346 | as ``pre_doit`` and ``post_doit`` calls in the kernel (these properties should | |
347 | be ignored by user space). | |
348 | ||
349 | mcast-groups | |
350 | ------------ | |
351 | ||
352 | This section lists the multicast groups of the family. | |
353 | ||
354 | list | |
355 | ~~~~ | |
356 | ||
357 | The only property of ``mcast-groups`` for ``genetlink``, holds the list | |
358 | of groups. | |
359 | ||
360 | Multicast group properties | |
361 | -------------------------- | |
362 | ||
363 | name | |
364 | ~~~~ | |
365 | ||
366 | Uniquely identifies the multicast group in the family. Similarly to | |
367 | Family ID, Multicast Group ID needs to be resolved at runtime, based | |
368 | on the name. | |
369 | ||
370 | .. _attr_types: | |
371 | ||
372 | Attribute types | |
373 | =============== | |
374 | ||
375 | This section describes the attribute types supported by the ``genetlink`` | |
376 | compatibility level. Refer to documentation of different levels for additional | |
377 | attribute types. | |
378 | ||
379 | Scalar integer types | |
380 | -------------------- | |
381 | ||
382 | Fixed-width integer types: | |
383 | ``u8``, ``u16``, ``u32``, ``u64``, ``s8``, ``s16``, ``s32``, ``s64``. | |
384 | ||
385 | Note that types smaller than 32 bit should be avoided as using them | |
386 | does not save any memory in Netlink messages (due to alignment). | |
387 | See :ref:`pad_type` for padding of 64 bit attributes. | |
388 | ||
389 | The payload of the attribute is the integer in host order unless ``byte-order`` | |
390 | specifies otherwise. | |
391 | ||
392 | .. _pad_type: | |
393 | ||
394 | pad | |
395 | --- | |
396 | ||
397 | Special attribute type used for padding attributes which require alignment | |
398 | bigger than standard 4B alignment required by netlink (e.g. 64 bit integers). | |
399 | There can only be a single attribute of the ``pad`` type in any attribute set | |
400 | and it should be automatically used for padding when needed. | |
401 | ||
402 | flag | |
403 | ---- | |
404 | ||
405 | Attribute with no payload, its presence is the entire information. | |
406 | ||
407 | binary | |
408 | ------ | |
409 | ||
410 | Raw binary data attribute, the contents are opaque to generic code. | |
411 | ||
412 | string | |
413 | ------ | |
414 | ||
415 | Character string. Unless ``checks`` has ``unterminated-ok`` set to ``true`` | |
416 | the string is required to be null terminated. | |
417 | ``max-len`` in ``checks`` indicates the longest possible string, | |
418 | if not present the length of the string is unbounded. | |
419 | ||
420 | Note that ``max-len`` does not count the terminating character. | |
421 | ||
422 | nest | |
423 | ---- | |
424 | ||
425 | Attribute containing other (nested) attributes. | |
426 | ``nested-attributes`` specifies which attribute set is used inside. |