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