userspace-api/netlink/specs.rst

1 .. SPDX-License-Identifier: BSD-3-Clause
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
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 -----------
103 Array of type and constant definitions.
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.
138 Array of names of the entries for ``enum`` and ``flags``.
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 --------------
151 This property contains information about netlink attributes of the family.
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
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
173 subset-of
176 Re-defines a portion of another set (a fractional set).
190 --------------------
208 The ``value`` property can be skipped, in which case the attribute ID
226 enum-as-flags
234 nested-attributes
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.
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
267 used to define the type of array members in case array members are not
269 a C array of u32 values can be specified with ``type: binary`` and
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``.
297 to by the ``attribute-set`` property.
302 (the name of the GET operation is specified in the ``notify`` property).
309 property. Events are considered less idiomatic for netlink and notifications
315 The only property of ``operations`` for ``genetlink``, holds the list of
319 --------------------
333 attribute-set
354 (possibly the same as the operation holding this property) which shares
361 ``event`` property is mutually exclusive with ``notify``.
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 --------------------------
412 --------------------
414 Fixed-width integer types:
421 The payload of the attribute is the integer in host order unless ``byte-order``
427 ---
435 ----
440 ------
444 string  section in Attribute types
445 ------
447 Character string. Unless ``checks`` has ``unterminated-ok`` set to ``true``
448 the string is required to be null terminated.
449 ``max-len`` in ``checks`` indicates the longest possible string,
450 if not present the length of the string is unbounded.
452 Note that ``max-len`` does not count the terminating character.
455 ----
458 ``nested-attributes`` specifies which attribute set is used inside.