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