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