1.. SPDX-License-Identifier: BSD-3-Clause 2 3========================================= 4Netlink protocol specifications (in YAML) 5========================================= 6 7Netlink protocol specifications are complete, machine readable descriptions of 8Netlink protocols written in YAML. The goal of the specifications is to allow 9separating Netlink parsing from user space logic and minimize the amount of 10hand written Netlink code for each new family, command, attribute. 11Netlink specs should be complete and not depend on any other spec 12or C header file, making it easy to use in languages which can't include 13kernel headers directly. 14 15Internally kernel uses the YAML specs to generate: 16 17 - the C uAPI header 18 - documentation of the protocol as a ReST file 19 - policy tables for input attribute validation 20 - operation tables 21 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 under 28``((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)`` 29to allow for easy adoption in user space code. 30 31Compatibility levels 32==================== 33 34There are four schema levels for Netlink specs, from the simplest used 35by 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 that 37user capable of parsing more complex ``genetlink`` schemas is also compatible 38with simpler ones. The levels are: 39 40 - ``genetlink`` - most streamlined, should be used by all new families 41 - ``genetlink-c`` - superset of ``genetlink`` with extra attributes allowing 42 customization of define and enum type and value names; this schema should 43 be equivalent to ``genetlink`` for all implementations which don't interact 44 directly with C uAPI headers 45 - ``genetlink-legacy`` - Generic Netlink catch all schema supporting quirks of 46 all old genetlink families, strange attribute formats, binary structures etc. 47 - ``netlink-raw`` - catch all schema supporting pre-Generic Netlink protocols 48 such as ``NETLINK_ROUTE`` 49 50The definition of the schemas (in ``jsonschema``) can be found 51under ``Documentation/netlink/``. 52 53Schema structure 54================ 55 56YAML schema has the following conceptual sections: 57 58 - globals 59 - definitions 60 - attributes 61 - operations 62 - multicast groups 63 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 71genetlink 72========= 73 74Globals 75------- 76 77Attributes listed directly at the root level of the spec file. 78 79name 80~~~~ 81 82Name of the family. Name identifies the family in a unique way, since 83the Family IDs are allocated dynamically. 84 85version 86~~~~~~~ 87 88Generic Netlink family version, default is 1. 89 90protocol 91~~~~~~~~ 92 93The schema level, default is ``genetlink``, which is the only value 94allowed for new ``genetlink`` families. 95 96definitions 97----------- 98 99Array of type and constant definitions. 100 101name 102~~~~ 103 104Name of the type / constant. 105 106type 107~~~~ 108 109One of the following types: 110 111 - const - a single, standalone constant 112 - enum - defines an integer enumeration, with values for each entry 113 incrementing by 1, (e.g. 0, 1, 2, 3) 114 - flags - defines an integer enumeration, with values for each entry 115 occupying a bit, starting from bit 0, (e.g. 1, 2, 4, 8) 116 117value 118~~~~~ 119 120The value for the ``const``. 121 122value-start 123~~~~~~~~~~~ 124 125The first value for ``enum`` and ``flags``, allows overriding the default 126start value of ``0`` (for ``enum``) and starting bit (for ``flags``). 127For ``flags`` ``value-start`` selects the starting bit, not the shifted value. 128 129Sparse enumerations are not supported. 130 131entries 132~~~~~~~ 133 134Array of names of the entries for ``enum`` and ``flags``. 135 136header 137~~~~~~ 138 139For C-compatible languages, header which already defines this value. 140In case the definition is shared by multiple families (e.g. ``IFNAMSIZ``) 141code generators for C-compatible languages may prefer to add an appropriate 142include instead of rendering a new definition. 143 144attribute-sets 145-------------- 146 147This property contains information about netlink attributes of the family. 148All families have at least one attribute set, most have multiple. 149``attribute-sets`` is an array, with each entry describing a single set. 150 151Note that the spec is "flattened" and is not meant to visually resemble 152the format of the netlink messages (unlike certain ad-hoc documentation 153formats seen in kernel comments). In the spec subordinate attribute sets 154are not defined inline as a nest, but defined in a separate attribute set 155referred to with a ``nested-attributes`` property of the container. 156 157Spec may also contain fractional sets - sets which contain a ``subset-of`` 158property. Such sets describe a section of a full set, allowing narrowing down 159which attributes are allowed in a nest or refining the validation criteria. 160Fractional sets can only be used in nests. They are not rendered to the uAPI 161in any fashion. 162 163name 164~~~~ 165 166Uniquely identifies the attribute set, operations and nested attributes 167refer to the sets by the ``name``. 168 169subset-of 170~~~~~~~~~ 171 172Re-defines a portion of another set (a fractional set). 173Allows narrowing down fields and changing validation criteria 174or even types of attributes depending on the nest in which they 175are contained. The ``value`` of each attribute in the fractional 176set is implicitly the same as in the main set. 177 178attributes 179~~~~~~~~~~ 180 181List of attributes in the set. 182 183Attribute properties 184-------------------- 185 186name 187~~~~ 188 189Identifies the attribute, unique within the set. 190 191type 192~~~~ 193 194Netlink attribute type, see :ref:`attr_types`. 195 196.. _assign_val: 197 198value 199~~~~~ 200 201Numerical attribute ID, used in serialized Netlink messages. 202The ``value`` property can be skipped, in which case the attribute ID 203will be the value of the previous attribute plus one (recursively) 204and ``1`` for the first attribute in the attribute set. 205 206Attributes (and operations) use ``1`` as the default value for the first 207entry (unlike enums in definitions which start from ``0``) because 208entry ``0`` is almost always reserved as undefined. Spec can explicitly 209set value to ``0`` if needed. 210 211Note that the ``value`` of an attribute is defined only in its main set 212(not in subsets). 213 214enum 215~~~~ 216 217For integer types specifies that values in the attribute belong 218to an ``enum`` or ``flags`` from the ``definitions`` section. 219 220enum-as-flags 221~~~~~~~~~~~~~ 222 223Treat ``enum`` as ``flags`` regardless of its type in ``definitions``. 224When both ``enum`` and ``flags`` forms are needed ``definitions`` should 225contain an ``enum`` and attributes which need the ``flags`` form should 226use this attribute. 227 228nested-attributes 229~~~~~~~~~~~~~~~~~ 230 231Identifies the attribute space for attributes nested within given attribute. 232Only valid for complex attributes which may have sub-attributes. 233 234multi-attr (arrays) 235~~~~~~~~~~~~~~~~~~~ 236 237Boolean property signifying that the attribute may be present multiple times. 238Allowing an attribute to repeat is the recommended way of implementing arrays 239(no extra nesting). 240 241byte-order 242~~~~~~~~~~ 243 244For integer types specifies attribute byte order - ``little-endian`` 245or ``big-endian``. 246 247checks 248~~~~~~ 249 250Input validation constraints used by the kernel. User space should query 251the policy of the running kernel using Generic Netlink introspection, 252rather than depend on what is specified in the spec file. 253 254The validation policy in the kernel is formed by combining the type 255definition (``type`` and ``nested-attributes``) and the ``checks``. 256 257operations 258---------- 259 260This section describes messages passed between the kernel and the user space. 261There are three types of entries in this section - operations, notifications 262and events. 263 264Operations describe the most common request - response communication. User 265sends a request and kernel replies. Each operation may contain any combination 266of the two modes familiar to netlink users - ``do`` and ``dump``. 267``do`` and ``dump`` in turn contain a combination of ``request`` and 268``response`` properties. If no explicit message with attributes is passed 269in a given direction (e.g. a ``dump`` which does not accept filter, or a ``do`` 270of a SET operation to which the kernel responds with just the netlink error 271code) ``request`` or ``response`` section can be skipped. 272``request`` and ``response`` sections list the attributes allowed in a message. 273The list contains only the names of attributes from a set referred 274to by the ``attribute-set`` property. 275 276Notifications and events both refer to the asynchronous messages sent by 277the kernel to members of a multicast group. The difference between the 278two is that a notification shares its contents with a GET operation 279(the name of the GET operation is specified in the ``notify`` property). 280This arrangement is commonly used for notifications about 281objects where the notification carries the full object definition. 282 283Events are more focused and carry only a subset of information rather than full 284object state (a made up example would be a link state change event with just 285the interface name and the new link state). Events contain the ``event`` 286property. Events are considered less idiomatic for netlink and notifications 287should be preferred. 288 289list 290~~~~ 291 292The only property of ``operations`` for ``genetlink``, holds the list of 293operations, notifications etc. 294 295Operation properties 296-------------------- 297 298name 299~~~~ 300 301Identifies the operation. 302 303value 304~~~~~ 305 306Numerical message ID, used in serialized Netlink messages. 307The same enumeration rules are applied as to 308:ref:`attribute values<assign_val>`. 309 310attribute-set 311~~~~~~~~~~~~~ 312 313Specifies the attribute set contained within the message. 314 315do 316~~~ 317 318Specification for the ``doit`` request. Should contain ``request``, ``reply`` 319or both of these properties, each holding a :ref:`attr_list`. 320 321dump 322~~~~ 323 324Specification for the ``dumpit`` request. Should contain ``request``, ``reply`` 325or both of these properties, each holding a :ref:`attr_list`. 326 327notify 328~~~~~~ 329 330Designates the message as a notification. Contains the name of the operation 331(possibly the same as the operation holding this property) which shares 332the contents with the notification (``do``). 333 334event 335~~~~~ 336 337Specification of attributes in the event, holds a :ref:`attr_list`. 338``event`` property is mutually exclusive with ``notify``. 339 340mcgrp 341~~~~~ 342 343Used with ``event`` and ``notify``, specifies which multicast group 344message belongs to. 345 346.. _attr_list: 347 348Message attribute list 349---------------------- 350 351``request``, ``reply`` and ``event`` properties have a single ``attributes`` 352property which holds the list of attribute names. 353 354Messages can also define ``pre`` and ``post`` properties which will be rendered 355as ``pre_doit`` and ``post_doit`` calls in the kernel (these properties should 356be ignored by user space). 357 358mcast-groups 359------------ 360 361This section lists the multicast groups of the family. 362 363list 364~~~~ 365 366The only property of ``mcast-groups`` for ``genetlink``, holds the list 367of groups. 368 369Multicast group properties 370-------------------------- 371 372name 373~~~~ 374 375Uniquely identifies the multicast group in the family. Similarly to 376Family ID, Multicast Group ID needs to be resolved at runtime, based 377on the name. 378 379.. _attr_types: 380 381Attribute types 382=============== 383 384This section describes the attribute types supported by the ``genetlink`` 385compatibility level. Refer to documentation of different levels for additional 386attribute types. 387 388Scalar integer types 389-------------------- 390 391Fixed-width integer types: 392``u8``, ``u16``, ``u32``, ``u64``, ``s8``, ``s16``, ``s32``, ``s64``. 393 394Note that types smaller than 32 bit should be avoided as using them 395does not save any memory in Netlink messages (due to alignment). 396See :ref:`pad_type` for padding of 64 bit attributes. 397 398The payload of the attribute is the integer in host order unless ``byte-order`` 399specifies otherwise. 400 401.. _pad_type: 402 403pad 404--- 405 406Special attribute type used for padding attributes which require alignment 407bigger than standard 4B alignment required by netlink (e.g. 64 bit integers). 408There can only be a single attribute of the ``pad`` type in any attribute set 409and it should be automatically used for padding when needed. 410 411flag 412---- 413 414Attribute with no payload, its presence is the entire information. 415 416binary 417------ 418 419Raw binary data attribute, the contents are opaque to generic code. 420 421string 422------ 423 424Character string. Unless ``checks`` has ``unterminated-ok`` set to ``true`` 425the string is required to be null terminated. 426``max-len`` in ``checks`` indicates the longest possible string, 427if not present the length of the string is unbounded. 428 429Note that ``max-len`` does not count the terminating character. 430 431nest 432---- 433 434Attribute containing other (nested) attributes. 435``nested-attributes`` specifies which attribute set is used inside. 436