userspace-api/netlink/specs.rst

1 .. SPDX-License-Identifier: BSD-3-Clause
10 hand written Netlink code for each new family, command, attribute.
17  - the C uAPI header
18  - documentation of the protocol as a ReST file
19  - policy tables for input attribute validation
20  - operation tables
25 See :doc:`intro-specs` for a practical starting guide.
28 ``((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)``
40  - ``genetlink`` - most streamlined, should be used by all new families
41  - ``genetlink-c`` - superset of ``genetlink`` with extra attributes allowing
45  - ``genetlink-legacy`` - Generic Netlink catch all schema supporting quirks of
46    all old genetlink families, strange attribute formats, binary structures etc.
47  - ``netlink-raw`` - catch all schema supporting pre-Generic Netlink protocols
58  - globals
59  - definitions
60  - attributes
61  - operations
62  - multicast groups
65 sub-property documenting the defined object.
68 schema. See the documentation of :doc:`genetlink-c <c-code-gen>`
71 See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>` for
79 -------
101 -----------
115  - const - a single, standalone constant
116  - enum - defines an integer enumeration, with values for each entry
118  - flags - defines an integer enumeration, with values for each entry
126 value-start
131 For ``flags`` ``value-start`` selects the starting bit, not the shifted value.
143 For C-compatible languages, header which already defines this value.
145 code generators for C-compatible languages may prefer to add an appropriate
148 attribute-sets
149 --------------
152 All families have at least one attribute set, most have multiple.
153 ``attribute-sets`` is an array, with each entry describing a single set.
156 the format of the netlink messages (unlike certain ad-hoc documentation
157 formats seen in kernel comments). In the spec subordinate attribute sets
158 are not defined inline as a nest, but defined in a separate attribute set
159 referred to with a ``nested-attributes`` property of the container.
161 Spec may also contain fractional sets - sets which contain a ``subset-of``
162 property. Such sets describe a section of a full set, allowing narrowing down
170 Uniquely identifies the attribute set, operations and nested attributes
173 subset-of
176 Re-defines a portion of another set (a fractional set).
179 are contained. The ``value`` of each attribute in the fractional
180 set is implicitly the same as in the main set.
185 List of attributes in the set.
189 Attribute properties
190 --------------------
195 Identifies the attribute, unique within the set.
200 Netlink attribute type, see :ref:`attr_types`.
207 Numerical attribute ID, used in serialized Netlink messages.
208 The ``value`` property can be skipped, in which case the attribute ID
209 will be the value of the previous attribute plus one (recursively)
210 and ``1`` for the first attribute in the attribute set.
215 set value to ``0`` if needed.
217 Note that the ``value`` of an attribute is defined only in its main set
223 For integer types specifies that values in the attribute belong
226 enum-as-flags
232 use this attribute.
234 nested-attributes
237 Identifies the attribute space for attributes nested within given attribute.
238 Only valid for complex attributes which may have sub-attributes.
240 multi-attr (arrays)
243 Boolean property signifying that the attribute may be present multiple times.
244 Allowing an attribute to repeat is the recommended way of implementing arrays
247 byte-order
250 For integer types specifies attribute byte order - ``little-endian``
251 or ``big-endian``.
261 definition (``type`` and ``nested-attributes``) and the ``checks``.
263 sub-type
266 Legacy families have special ways of expressing arrays. ``sub-type`` can be
268 fully defined as attributes (in a bona fide attribute space). For instance
270 ``sub-type: u32``. Binary types and legacy array formats are described in
271 more detail in :doc:`genetlink-legacy`.
273 display-hint
281 ----------
284 There are three types of entries in this section - operations, notifications
287 Operations describe the most common request - response communication. User
289 of the two modes familiar to netlink users - ``do`` and ``dump``.
293 of a SET operation to which the kernel responds with just the netlink error
296 The list contains only the names of attributes from a set referred
297 to by the ``attribute-set`` property.
319 --------------------
331 :ref:`attribute values<assign_val>`.
333 attribute-set  subsection
336 Specifies the attribute set contained within the message.
371 Message attribute list
372 ----------------------
375 property which holds the list of attribute names.
381 mcast-groups
382 ------------
389 The only property of ``mcast-groups`` for ``genetlink``, holds the list
393 --------------------------
404 Attribute types
407 This section describes the attribute types supported by the ``genetlink``
409 attribute types.
412 --------------------
414 Fixed-width integer types:
421 The payload of the attribute is the integer in host order unless ``byte-order``
427 ---
429 Special attribute type used for padding attributes which require alignment
431 There can only be a single attribute of the ``pad`` type in any attribute set
435 ----
437 Attribute with no payload, its presence is the entire information.
440 ------
442 Raw binary data attribute, the contents are opaque to generic code.
445 ------
447 Character string. Unless ``checks`` has ``unterminated-ok`` set to ``true``
449 ``max-len`` in ``checks`` indicates the longest possible string,
452 Note that ``max-len`` does not count the terminating character.
455 ----
457 Attribute containing other (nested) attributes.
458 ``nested-attributes`` specifies which attribute set is used inside.