1 .. SPDX-License-Identifier: BSD-3-Clause
10 hand written Netlink code for each new family, command, attribute.
12 or C header file, making it easy to use in languages which can't include
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
44    directly with C uAPI headers
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>`
69 for information on how C names are derived from name properties.
71 See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>` for
79 -------
83 name  subsection
86 Name of the family. Name identifies the family in a unique way, since
87 the Family IDs are allocated dynamically.
92 Generic Netlink family version, default is 1.
101 -----------
105 name  subsection
108 Name of the type / constant.
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 --------------
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``
167 name  subsection
171 refer to the sets by the ``name``.
173 subset-of
176 Re-defines a portion of another set (a fractional set).
190 --------------------
192 name  subsection
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
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).
308 the interface name and the new link state). Events contain the ``event``
319 --------------------
321 name  subsection
333 attribute-set
353 Designates the message as a notification. Contains the name of the operation
372 ----------------------
381 mcast-groups
382 ------------
384 This section lists the multicast groups of the family.
389 The only property of ``mcast-groups`` for ``genetlink``, holds the list
393 --------------------------
395 name  subsection
398 Uniquely identifies the multicast group in the family. Similarly to
399 Family ID, Multicast Group ID needs to be resolved at runtime, based
400 on the name.
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.