468 lines · plain
1.. SPDX-License-Identifier: BSD-3-Clause2 3=========================================4Netlink protocol specifications (in YAML)5=========================================6 7Netlink protocol specifications are complete, machine readable descriptions of8Netlink protocols written in YAML. The goal of the specifications is to allow9separating Netlink parsing from user space logic and minimize the amount of10hand written Netlink code for each new family, command, attribute.11Netlink specs should be complete and not depend on any other spec12or C header file, making it easy to use in languages which can't include13kernel headers directly.14 15Internally kernel uses the YAML specs to generate:16 17 - the C uAPI header18 - documentation of the protocol as a ReST file - see :ref:`Documentation/networking/netlink_spec/index.rst <specs>`19 - policy tables for input attribute validation20 - operation tables21 22YAML specifications can be found under ``Documentation/netlink/specs/``23 24This document describes details of the schema.25See :doc:`intro-specs` for a practical starting guide.26 27All specs must be licensed under28``((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)``29to allow for easy adoption in user space code.30 31Compatibility levels32====================33 34There are four schema levels for Netlink specs, from the simplest used35by new families to the most complex covering all the quirks of the old ones.36Each next level inherits the attributes of the previous level, meaning that37user capable of parsing more complex ``genetlink`` schemas is also compatible38with simpler ones. The levels are:39 40 - ``genetlink`` - most streamlined, should be used by all new families41 - ``genetlink-c`` - superset of ``genetlink`` with extra attributes allowing42 customization of define and enum type and value names; this schema should43 be equivalent to ``genetlink`` for all implementations which don't interact44 directly with C uAPI headers45 - ``genetlink-legacy`` - Generic Netlink catch all schema supporting quirks of46 all old genetlink families, strange attribute formats, binary structures etc.47 - ``netlink-raw`` - catch all schema supporting pre-Generic Netlink protocols48 such as ``NETLINK_ROUTE``49 50The definition of the schemas (in ``jsonschema``) can be found51under ``Documentation/netlink/``.52 53Schema structure54================55 56YAML schema has the following conceptual sections:57 58 - globals59 - definitions60 - attributes61 - operations62 - multicast groups63 64Most properties in the schema accept (or in fact require) a ``doc``65sub-property documenting the defined object.66 67The following sections describe the properties of the most modern ``genetlink``68schema. See the documentation of :doc:`genetlink-c <c-code-gen>`69for information on how C names are derived from name properties.70 71See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>` for72information on the Netlink specification properties that are only relevant to73the kernel space and not part of the user space API.74 75genetlink76=========77 78Globals79-------80 81Attributes listed directly at the root level of the spec file.82 83name84~~~~85 86Name of the family. Name identifies the family in a unique way, since87the Family IDs are allocated dynamically.88 89protocol90~~~~~~~~91 92The schema level, default is ``genetlink``, which is the only value93allowed for new ``genetlink`` families.94 95definitions96-----------97 98Array of type and constant definitions.99 100name101~~~~102 103Name of the type / constant.104 105type106~~~~107 108One of the following types:109 110 - const - a single, standalone constant111 - enum - defines an integer enumeration, with values for each entry112 incrementing by 1, (e.g. 0, 1, 2, 3)113 - flags - defines an integer enumeration, with values for each entry114 occupying a bit, starting from bit 0, (e.g. 1, 2, 4, 8)115 116value117~~~~~118 119The value for the ``const``.120 121value-start122~~~~~~~~~~~123 124The first value for ``enum`` and ``flags``, allows overriding the default125start value of ``0`` (for ``enum``) and starting bit (for ``flags``).126For ``flags`` ``value-start`` selects the starting bit, not the shifted value.127 128Sparse enumerations are not supported.129 130entries131~~~~~~~132 133Array of names of the entries for ``enum`` and ``flags``.134 135header136~~~~~~137 138For C-compatible languages, header which already defines this value.139In case the definition is shared by multiple families (e.g. ``IFNAMSIZ``)140code generators for C-compatible languages may prefer to add an appropriate141include instead of rendering a new definition.142 143attribute-sets144--------------145 146This property contains information about netlink attributes of the family.147All families have at least one attribute set, most have multiple.148``attribute-sets`` is an array, with each entry describing a single set.149 150Note that the spec is "flattened" and is not meant to visually resemble151the format of the netlink messages (unlike certain ad-hoc documentation152formats seen in kernel comments). In the spec subordinate attribute sets153are not defined inline as a nest, but defined in a separate attribute set154referred to with a ``nested-attributes`` property of the container.155 156Spec may also contain fractional sets - sets which contain a ``subset-of``157property. Such sets describe a section of a full set, allowing narrowing down158which attributes are allowed in a nest or refining the validation criteria.159Fractional sets can only be used in nests. They are not rendered to the uAPI160in any fashion.161 162name163~~~~164 165Uniquely identifies the attribute set, operations and nested attributes166refer to the sets by the ``name``.167 168subset-of169~~~~~~~~~170 171Re-defines a portion of another set (a fractional set).172Allows narrowing down fields and changing validation criteria173or even types of attributes depending on the nest in which they174are contained. The ``value`` of each attribute in the fractional175set is implicitly the same as in the main set.176 177attributes178~~~~~~~~~~179 180List of attributes in the set.181 182.. _attribute_properties:183 184Attribute properties185--------------------186 187name188~~~~189 190Identifies the attribute, unique within the set.191 192type193~~~~194 195Netlink attribute type, see :ref:`attr_types`.196 197.. _assign_val:198 199value200~~~~~201 202Numerical attribute ID, used in serialized Netlink messages.203The ``value`` property can be skipped, in which case the attribute ID204will be the value of the previous attribute plus one (recursively)205and ``1`` for the first attribute in the attribute set.206 207Attributes (and operations) use ``1`` as the default value for the first208entry (unlike enums in definitions which start from ``0``) because209entry ``0`` is almost always reserved as undefined. Spec can explicitly210set value to ``0`` if needed.211 212Note that the ``value`` of an attribute is defined only in its main set213(not in subsets).214 215enum216~~~~217 218For integer types specifies that values in the attribute belong219to an ``enum`` or ``flags`` from the ``definitions`` section.220 221enum-as-flags222~~~~~~~~~~~~~223 224Treat ``enum`` as ``flags`` regardless of its type in ``definitions``.225When both ``enum`` and ``flags`` forms are needed ``definitions`` should226contain an ``enum`` and attributes which need the ``flags`` form should227use this attribute.228 229nested-attributes230~~~~~~~~~~~~~~~~~231 232Identifies the attribute space for attributes nested within given attribute.233Only valid for complex attributes which may have sub-attributes.234 235multi-attr (arrays)236~~~~~~~~~~~~~~~~~~~237 238Boolean property signifying that the attribute may be present multiple times.239Allowing an attribute to repeat is the recommended way of implementing arrays240(no extra nesting).241 242byte-order243~~~~~~~~~~244 245For integer types specifies attribute byte order - ``little-endian``246or ``big-endian``.247 248checks249~~~~~~250 251Input validation constraints used by the kernel. User space should query252the policy of the running kernel using Generic Netlink introspection,253rather than depend on what is specified in the spec file.254 255The validation policy in the kernel is formed by combining the type256definition (``type`` and ``nested-attributes``) and the ``checks``.257 258sub-type259~~~~~~~~260 261Legacy families have special ways of expressing arrays. ``sub-type`` can be262used to define the type of array members in case array members are not263fully defined as attributes (in a bona fide attribute space). For instance264a C array of u32 values can be specified with ``type: binary`` and265``sub-type: u32``. Binary types and legacy array formats are described in266more detail in :doc:`genetlink-legacy`.267 268display-hint269~~~~~~~~~~~~270 271Optional format indicator that is intended only for choosing the right272formatting mechanism when displaying values of this type. Currently supported273hints are ``hex``, ``mac``, ``fddi``, ``ipv4``, ``ipv6`` and ``uuid``.274 275operations276----------277 278This section describes messages passed between the kernel and the user space.279There are three types of entries in this section - operations, notifications280and events.281 282Operations describe the most common request - response communication. User283sends a request and kernel replies. Each operation may contain any combination284of the two modes familiar to netlink users - ``do`` and ``dump``.285``do`` and ``dump`` in turn contain a combination of ``request`` and286``response`` properties. If no explicit message with attributes is passed287in a given direction (e.g. a ``dump`` which does not accept filter, or a ``do``288of a SET operation to which the kernel responds with just the netlink error289code) ``request`` or ``response`` section can be skipped.290``request`` and ``response`` sections list the attributes allowed in a message.291The list contains only the names of attributes from a set referred292to by the ``attribute-set`` property.293 294Notifications and events both refer to the asynchronous messages sent by295the kernel to members of a multicast group. The difference between the296two is that a notification shares its contents with a GET operation297(the name of the GET operation is specified in the ``notify`` property).298This arrangement is commonly used for notifications about299objects where the notification carries the full object definition.300 301Events are more focused and carry only a subset of information rather than full302object state (a made up example would be a link state change event with just303the interface name and the new link state). Events contain the ``event``304property. Events are considered less idiomatic for netlink and notifications305should be preferred.306 307list308~~~~309 310The only property of ``operations`` for ``genetlink``, holds the list of311operations, notifications etc.312 313Operation properties314--------------------315 316name317~~~~318 319Identifies the operation.320 321value322~~~~~323 324Numerical message ID, used in serialized Netlink messages.325The same enumeration rules are applied as to326:ref:`attribute values<assign_val>`.327 328attribute-set329~~~~~~~~~~~~~330 331Specifies the attribute set contained within the message.332 333do334~~~335 336Specification for the ``doit`` request. Should contain ``request``, ``reply``337or both of these properties, each holding a :ref:`attr_list`.338 339dump340~~~~341 342Specification for the ``dumpit`` request. Should contain ``request``, ``reply``343or both of these properties, each holding a :ref:`attr_list`.344 345notify346~~~~~~347 348Designates the message as a notification. Contains the name of the operation349(possibly the same as the operation holding this property) which shares350the contents with the notification (``do``).351 352event353~~~~~354 355Specification of attributes in the event, holds a :ref:`attr_list`.356``event`` property is mutually exclusive with ``notify``.357 358mcgrp359~~~~~360 361Used with ``event`` and ``notify``, specifies which multicast group362message belongs to.363 364.. _attr_list:365 366Message attribute list367----------------------368 369``request``, ``reply`` and ``event`` properties have a single ``attributes``370property which holds the list of attribute names.371 372Messages can also define ``pre`` and ``post`` properties which will be rendered373as ``pre_doit`` and ``post_doit`` calls in the kernel (these properties should374be ignored by user space).375 376mcast-groups377------------378 379This section lists the multicast groups of the family.380 381list382~~~~383 384The only property of ``mcast-groups`` for ``genetlink``, holds the list385of groups.386 387Multicast group properties388--------------------------389 390name391~~~~392 393Uniquely identifies the multicast group in the family. Similarly to394Family ID, Multicast Group ID needs to be resolved at runtime, based395on the name.396 397.. _attr_types:398 399Attribute types400===============401 402This section describes the attribute types supported by the ``genetlink``403compatibility level. Refer to documentation of different levels for additional404attribute types.405 406Common integer types407--------------------408 409``sint`` and ``uint`` represent signed and unsigned 64 bit integers.410If the value can fit on 32 bits only 32 bits are carried in netlink411messages, otherwise full 64 bits are carried. Note that the payload412is only aligned to 4B, so the full 64 bit value may be unaligned!413 414Common integer types should be preferred over fix-width types in majority415of cases.416 417Fix-width integer types418-----------------------419 420Fixed-width integer types include:421``u8``, ``u16``, ``u32``, ``u64``, ``s8``, ``s16``, ``s32``, ``s64``.422 423Note that types smaller than 32 bit should be avoided as using them424does not save any memory in Netlink messages (due to alignment).425See :ref:`pad_type` for padding of 64 bit attributes.426 427The payload of the attribute is the integer in host order unless ``byte-order``428specifies otherwise.429 43064 bit values are usually aligned by the kernel but it is recommended431that the user space is able to deal with unaligned values.432 433.. _pad_type:434 435pad436---437 438Special attribute type used for padding attributes which require alignment439bigger than standard 4B alignment required by netlink (e.g. 64 bit integers).440There can only be a single attribute of the ``pad`` type in any attribute set441and it should be automatically used for padding when needed.442 443flag444----445 446Attribute with no payload, its presence is the entire information.447 448binary449------450 451Raw binary data attribute, the contents are opaque to generic code.452 453string454------455 456Character string. Unless ``checks`` has ``unterminated-ok`` set to ``true``457the string is required to be null terminated.458``max-len`` in ``checks`` indicates the longest possible string,459if not present the length of the string is unbounded.460 461Note that ``max-len`` does not count the terminating character.462 463nest464----465 466Attribute containing other (nested) attributes.467``nested-attributes`` specifies which attribute set is used inside.468