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 -----------
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 --------------
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``
173 subset-of
176 Re-defines a portion of another set (a fractional set).
190 --------------------
226 enum-as-flags
234 nested-attributes
238 Only valid for complex attributes which may have sub-attributes.
240 multi-attr (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
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.
300 the kernel to members of a multicast group. The difference between the
319 --------------------
333 attribute-set
366 Used with ``event`` and ``notify``, specifies which multicast group
372 ----------------------
381 mcast-groups
382 ------------
389 The only property of ``mcast-groups`` for ``genetlink``, holds the list
392 Multicast group properties
393 --------------------------
398 Uniquely identifies the multicast group in the family. Similarly to
399 Family ID, Multicast Group ID needs to be resolved at runtime, based
412 --------------------
414 Fixed-width integer types:
421 The payload of the attribute is the integer in host order unless ``byte-order``
427 ---
435 ----
440 ------
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 ----
458 ``nested-attributes`` specifies which attribute set is used inside.