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 - see :ref:`Documentation/networking/netlink_spec/i…
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.
96 -----------
100 name  subsection
103 Name of the type / constant.
110  - const - a single, standalone constant
111  - enum - defines an integer enumeration, with values for each entry
113  - flags - defines an integer enumeration, with values for each entry
121 value-start
126 For ``flags`` ``value-start`` selects the starting bit, not the shifted value.
138 For C-compatible languages, header which already defines this value.
140 code generators for C-compatible languages may prefer to add an appropriate
143 attribute-sets
144 --------------
146 This property contains information about netlink attributes of the family.
148 ``attribute-sets`` is an array, with each entry describing a single set.
151 the format of the netlink messages (unlike certain ad-hoc documentation
154 referred to with a ``nested-attributes`` property of the container.
156 Spec may also contain fractional sets - sets which contain a ``subset-of``
162 name  subsection
166 refer to the sets by the ``name``.
168 subset-of
171 Re-defines a portion of another set (a fractional set).
185 --------------------
187 name  subsection
221 enum-as-flags
229 nested-attributes
233 Only valid for complex attributes which may have sub-attributes.
235 multi-attr (arrays)
242 byte-order
245 For integer types specifies attribute byte order - ``little-endian``
246 or ``big-endian``.
256 definition (``type`` and ``nested-attributes``) and the ``checks``.
258 sub-type
261 Legacy families have special ways of expressing arrays. ``sub-type`` can be
264 a C array of u32 values can be specified with ``type: binary`` and
265 ``sub-type: u32``. Binary types and legacy array formats are described in
266 more detail in :doc:`genetlink-legacy`.
268 display-hint
276 ----------
279 There are three types of entries in this section - operations, notifications
282 Operations describe the most common request - response communication. User
284 of the two modes familiar to netlink users - ``do`` and ``dump``.
292 to by the ``attribute-set`` property.
297 (the name of the GET operation is specified in the ``notify`` property).
303 the interface name and the new link state). Events contain the ``event``
314 --------------------
316 name  subsection
328 attribute-set
348 Designates the message as a notification. Contains the name of the operation
367 ----------------------
376 mcast-groups
377 ------------
379 This section lists the multicast groups of the family.
384 The only property of ``mcast-groups`` for ``genetlink``, holds the list
388 --------------------------
390 name  subsection
393 Uniquely identifies the multicast group in the family. Similarly to
394 Family ID, Multicast Group ID needs to be resolved at runtime, based
395 on the name.
407 --------------------
414 Common integer types should be preferred over fix-width types in majority
417 Fix-width integer types
418 -----------------------
420 Fixed-width integer types include:
427 The payload of the attribute is the integer in host order unless ``byte-order``
436 ---
444 ----
449 ------
454 ------
456 Character string. Unless ``checks`` has ``unterminated-ok`` set to ``true``
458 ``max-len`` in ``checks`` indicates the longest possible string,
461 Note that ``max-len`` does not count the terminating character.
464 ----
467 ``nested-attributes`` specifies which attribute set is used inside.