Documentation/netlink/netlink-raw.yaml

   1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
   2 %YAML 1.2
   3 ---
   4 $id: http://kernel.org/schemas/netlink/netlink-raw.yaml#
   5 $schema: https://json-schema.org/draft-07/schema
   6
   7 # Common defines
   8 $defs:
   9   uint:
  10     type: integer
  11     minimum: 0
  12   len-or-define:
  13     type: [ string, integer ]
  14     pattern: ^[0-9A-Za-z_-]+( - 1)?$
  15     minimum: 0
  16
  17 # Schema for specs
  18 title: Protocol
  19 description: Specification of a raw netlink protocol
  20 type: object
  21 required: [ name, doc, attribute-sets, operations ]
  22 additionalProperties: False
  23 properties:
  24   name:
  25     description: Name of the netlink family.
  26     type: string
  27   doc:
  28     type: string
  29   protocol:
  30     description: Schema compatibility level.
  31     enum: [ netlink-raw ] # Trim
  32   # Start netlink-raw
  33   protonum:
  34     description: Protocol number to use for netlink-raw
  35     type: integer
  36   # End netlink-raw
  37   uapi-header:
  38     description: Path to the uAPI header, default is linux/${family-name}.h
  39     type: string
  40   # Start genetlink-c
  41   c-family-name:
  42     description: Name of the define for the family name.
  43     type: string
  44   c-version-name:
  45     description: Name of the define for the version of the family.
  46     type: string
  47   max-by-define:
  48     description: Makes the number of attributes and commands be specified by a define, not an enum value.
  49     type: boolean
  50   cmd-max-name:
  51     description: Name of the define for the last operation in the list.
  52     type: string
  53   cmd-cnt-name:
  54     description: The explicit name for constant holding the count of operations (last operation + 1).
  55     type: string
  56   # End genetlink-c
  57   # Start genetlink-legacy
  58   kernel-policy:
  59     description: |
  60       Defines if the input policy in the kernel is global, per-operation, or split per operation type.
  61       Default is split.
  62     enum: [ split, per-op, global ]
  63   # End genetlink-legacy
  64
  65   definitions:
  66     description: List of type and constant definitions (enums, flags, defines).
  67     type: array
  68     items:
  69       type: object
  70       required: [ type, name ]
  71       additionalProperties: False
  72       properties:
  73         name:
  74           type: string
  75         header:
  76           description: For C-compatible languages, header which already defines this value.
  77           type: string
  78         type:
  79           enum: [ const, enum, flags, struct ] # Trim
  80         doc:
  81           type: string
  82         # For const
  83         value:
  84           description: For const - the value.
  85           type: [ string, integer ]
  86         # For enum and flags
  87         value-start:
  88           description: For enum or flags the literal initializer for the first value.
  89           type: [ string, integer ]
  90         entries:
  91           description: For enum or flags array of values.
  92           type: array
  93           items:
  94             oneOf:
  95               - type: string
  96               - type: object
  97                 required: [ name ]
  98                 additionalProperties: False
  99                 properties:
 100                   name:
 101                     type: string
 102                   value:
 103                     type: integer
 104                   doc:
 105                     type: string
 106         render-max:
 107           description: Render the max members for this enum.
 108           type: boolean
 109         # Start genetlink-c
 110         enum-name:
 111           description: Name for enum, if empty no name will be used.
 112           type: [ string, "null" ]
 113         name-prefix:
 114           description: For enum the prefix of the values, optional.
 115           type: string
 116         # End genetlink-c
 117         # Start genetlink-legacy
 118         members:
 119           description: List of struct members. Only scalars and strings members allowed.
 120           type: array
 121           items:
 122             type: object
 123             required: [ name, type ]
 124             additionalProperties: False
 125             properties:
 126               name:
 127                 type: string
 128               type:
 129                 description: |
 130                   The netlink attribute type. Members of type 'binary' or 'pad'
 131                   must also have the 'len' property set.
 132                 enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary, pad ]
 133               len:
 134                 $ref: '#/$defs/len-or-define'
 135               byte-order:
 136                 enum: [ little-endian, big-endian ]
 137               doc:
 138                 description: Documentation for the struct member attribute.
 139                 type: string
 140               enum:
 141                 description: Name of the enum type used for the attribute.
 142                 type: string
 143               enum-as-flags:
 144                 description: |
 145                   Treat the enum as flags. In most cases enum is either used as flags or as values.
 146                   Sometimes, however, both forms are necessary, in which case header contains the enum
 147                   form while specific attributes may request to convert the values into a bitfield.
 148                 type: boolean
 149               display-hint: &display-hint
 150                 description: |
 151                   Optional format indicator that is intended only for choosing
 152                   the right formatting mechanism when displaying values of this
 153                   type.
 154                 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
 155               struct:
 156                 description: Name of the nested struct type.
 157                 type: string
 158             if:
 159               properties:
 160                 type:
 161                   const: pad
 162             then:
 163               required: [ len ]
 164             if:
 165               properties:
 166                 type:
 167                   const: binary
 168             then:
 169               oneOf:
 170                 - required: [ len ]
 171                 - required: [ struct ]
 172         # End genetlink-legacy
 173
 174   attribute-sets:
 175     description: Definition of attribute spaces for this family.
 176     type: array
 177     items:
 178       description: Definition of a single attribute space.
 179       type: object
 180       required: [ name, attributes ]
 181       additionalProperties: False
 182       properties:
 183         name:
 184           description: |
 185             Name used when referring to this space in other definitions, not used outside of the spec.
 186           type: string
 187         name-prefix:
 188           description: |
 189             Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
 190           type: string
 191         enum-name:
 192           description: |
 193             Name for the enum type of the attribute, if empty no name will be used.
 194           type: [ string, "null" ]
 195         doc:
 196           description: Documentation of the space.
 197           type: string
 198         subset-of:
 199           description: |
 200             Name of another space which this is a logical part of. Sub-spaces can be used to define
 201             a limited group of attributes which are used in a nest.
 202           type: string
 203         # Start genetlink-c
 204         attr-cnt-name:
 205           description: The explicit name for constant holding the count of attributes (last attr + 1).
 206           type: string
 207         attr-max-name:
 208           description: The explicit name for last member of attribute enum.
 209           type: string
 210         # End genetlink-c
 211         attributes:
 212           description: List of attributes in the space.
 213           type: array
 214           items:
 215             type: object
 216             required: [ name ]
 217             additionalProperties: False
 218             properties:
 219               name:
 220                 type: string
 221               type: &attr-type
 222                 description: The netlink attribute type
 223                 enum: [ unused, pad, flag, binary, bitfield32,
 224                         u8, u16, u32, u64, s8, s16, s32, s64,
 225                         string, nest, indexed-array, nest-type-value,
 226                         sub-message ]
 227               doc:
 228                 description: Documentation of the attribute.
 229                 type: string
 230               value:
 231                 description: Value for the enum item representing this attribute in the uAPI.
 232                 $ref: '#/$defs/uint'
 233               type-value:
 234                 description: Name of the value extracted from the type of a nest-type-value attribute.
 235                 type: array
 236                 items:
 237                   type: string
 238               byte-order:
 239                 enum: [ little-endian, big-endian ]
 240               multi-attr:
 241                 type: boolean
 242               nested-attributes:
 243                 description: Name of the space (sub-space) used inside the attribute.
 244                 type: string
 245               enum:
 246                 description: Name of the enum type used for the attribute.
 247                 type: string
 248               enum-as-flags:
 249                 description: |
 250                   Treat the enum as flags. In most cases enum is either used as flags or as values.
 251                   Sometimes, however, both forms are necessary, in which case header contains the enum
 252                   form while specific attributes may request to convert the values into a bitfield.
 253                 type: boolean
 254               checks:
 255                 description: Kernel input validation.
 256                 type: object
 257                 additionalProperties: False
 258                 properties:
 259                   flags-mask:
 260                     description: Name of the flags constant on which to base mask (unsigned scalar types only).
 261                     type: string
 262                   min:
 263                     description: Min value for an integer attribute.
 264                     type: integer
 265                   min-len:
 266                     description: Min length for a binary attribute.
 267                     $ref: '#/$defs/len-or-define'
 268                   max-len:
 269                     description: Max length for a string or a binary attribute.
 270                     $ref: '#/$defs/len-or-define'
 271                   exact-len:
 272                     description: Exact length for a string or a binary attribute.
 273                     $ref: '#/$defs/len-or-define'
 274                   unterminated-ok:
 275                     description: |
 276                       For string attributes, do not check whether attribute
 277                       contains the terminating null character.
 278                     type: boolean
 279               sub-type: *attr-type
 280               display-hint: *display-hint
 281               # Start genetlink-c
 282               name-prefix:
 283                 type: string
 284               # End genetlink-c
 285               # Start genetlink-legacy
 286               struct:
 287                 description: Name of the struct type used for the attribute.
 288                 type: string
 289               # End genetlink-legacy
 290               # Start netlink-raw
 291               sub-message:
 292                 description: |
 293                   Name of the sub-message definition to use for the attribute.
 294                 type: string
 295               selector:
 296                 description: |
 297                   Name of the attribute to use for dynamic selection of sub-message
 298                   format specifier.
 299                 type: string
 300               # End netlink-raw
 301
 302       # Make sure name-prefix does not appear in subsets (subsets inherit naming)
 303       dependencies:
 304         name-prefix:
 305           not:
 306             required: [ subset-of ]
 307         subset-of:
 308           not:
 309             required: [ name-prefix ]
 310
 311       # type property is only required if not in subset definition
 312       if:
 313         properties:
 314           subset-of:
 315             not:
 316               type: string
 317       then:
 318         properties:
 319           attributes:
 320             items:
 321               required: [ type ]
 322
 323   # Start netlink-raw
 324   sub-messages:
 325     description: Definition of sub message attributes
 326     type: array
 327     items:
 328       type: object
 329       additionalProperties: False
 330       required: [ name, formats ]
 331       properties:
 332         name:
 333           description: Name of the sub-message definition
 334           type: string
 335         formats:
 336           description: Dynamically selected format specifiers
 337           type: array
 338           items:
 339             type: object
 340             additionalProperties: False
 341             required: [ value ]
 342             properties:
 343               value:
 344                 description: |
 345                   Value to match for dynamic selection of sub-message format
 346                   specifier.
 347                 type: string
 348               fixed-header:
 349                 description: |
 350                   Name of the struct definition to use as the fixed header
 351                   for the sub message.
 352                 type: string
 353               attribute-set:
 354                 description: |
 355                   Name of the attribute space from which to resolve attributes
 356                   in the sub message.
 357                 type: string
 358   # End netlink-raw
 359
 360   operations:
 361     description: Operations supported by the protocol.
 362     type: object
 363     required: [ list ]
 364     additionalProperties: False
 365     properties:
 366       enum-model:
 367         description: |
 368           The model of assigning values to the operations.
 369           "unified" is the recommended model where all message types belong
 370           to a single enum.
 371           "directional" has the messages sent to the kernel and from the kernel
 372           enumerated separately.
 373         enum: [ unified, directional ] # Trim
 374       name-prefix:
 375         description: |
 376           Prefix for the C enum name of the command. The name is formed by concatenating
 377           the prefix with the upper case name of the command, with dashes replaced by underscores.
 378         type: string
 379       enum-name:
 380         description: |
 381           Name for the enum type with commands, if empty no name will be used.
 382         type: [ string, "null" ]
 383       async-prefix:
 384         description: Same as name-prefix but used to render notifications and events to separate enum.
 385         type: string
 386       async-enum:
 387         description: |
 388           Name for the enum type with commands, if empty no name will be used.
 389         type: [ string, "null" ]
 390       # Start genetlink-legacy
 391       fixed-header: &fixed-header
 392         description: |
 393           Name of the structure defining the optional fixed-length protocol
 394           header. This header is placed in a message after the netlink and
 395           genetlink headers and before any attributes.
 396         type: string
 397       # End genetlink-legacy
 398       list:
 399         description: List of commands
 400         type: array
 401         items:
 402           type: object
 403           additionalProperties: False
 404           required: [ name, doc ]
 405           properties:
 406             name:
 407               description: Name of the operation, also defining its C enum value in uAPI.
 408               type: string
 409             doc:
 410               description: Documentation for the command.
 411               type: string
 412             value:
 413               description: Value for the enum in the uAPI.
 414               $ref: '#/$defs/uint'
 415             attribute-set:
 416               description: |
 417                 Attribute space from which attributes directly in the requests and replies
 418                 to this command are defined.
 419               type: string
 420             flags: &cmd_flags
 421               description: Command flags.
 422               type: array
 423               items:
 424                 enum: [ admin-perm ]
 425             dont-validate:
 426               description: Kernel attribute validation flags.
 427               type: array
 428               items:
 429                 enum: [ strict, dump ]
 430             # Start genetlink-legacy
 431             fixed-header: *fixed-header
 432             # End genetlink-legacy
 433             do: &subop-type
 434               description: Main command handler.
 435               type: object
 436               additionalProperties: False
 437               properties:
 438                 request: &subop-attr-list
 439                   description: Definition of the request message for a given command.
 440                   type: object
 441                   additionalProperties: False
 442                   properties:
 443                     attributes:
 444                       description: |
 445                         Names of attributes from the attribute-set (not full attribute
 446                         definitions, just names).
 447                       type: array
 448                       items:
 449                         type: string
 450                     # Start genetlink-legacy
 451                     value:
 452                       description: |
 453                         ID of this message if value for request and response differ,
 454                         i.e. requests and responses have different message enums.
 455                       $ref: '#/$defs/uint'
 456                     # End genetlink-legacy
 457                 reply: *subop-attr-list
 458                 pre:
 459                   description: Hook for a function to run before the main callback (pre_doit or start).
 460                   type: string
 461                 post:
 462                   description: Hook for a function to run after the main callback (post_doit or done).
 463                   type: string
 464             dump: *subop-type
 465             notify:
 466               description: Name of the command sharing the reply type with this notification.
 467               type: string
 468             event:
 469               type: object
 470               additionalProperties: False
 471               properties:
 472                 attributes:
 473                   description: Explicit list of the attributes for the notification.
 474                   type: array
 475                   items:
 476                     type: string
 477             mcgrp:
 478               description: Name of the multicast group generating given notification.
 479               type: string
 480   mcast-groups:
 481     description: List of multicast groups.
 482     type: object
 483     required: [ list ]
 484     additionalProperties: False
 485     properties:
 486       list:
 487         description: List of groups.
 488         type: array
 489         items:
 490           type: object
 491           required: [ name ]
 492           additionalProperties: False
 493           properties:
 494             name:
 495               description: |
 496                 The name for the group, used to form the define and the value of the define.
 497               type: string
 498             # Start genetlink-c
 499             c-define-name:
 500               description: Override for the name of the define in C uAPI.
 501               type: string
 502             # End genetlink-c
 503             flags: *cmd_flags
 504             # Start netlink-raw
 505             value:
 506               description: Value of the netlink multicast group in the uAPI.
 507               type: integer
 508             # End netlink-raw