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             if:
 156               properties:
 157                 type:
 158                   oneOf:
 159                     - const: binary
 160                     - const: pad
 161             then:
 162               required: [ len ]
 163         # End genetlink-legacy
 164
 165   attribute-sets:
 166     description: Definition of attribute spaces for this family.
 167     type: array
 168     items:
 169       description: Definition of a single attribute space.
 170       type: object
 171       required: [ name, attributes ]
 172       additionalProperties: False
 173       properties:
 174         name:
 175           description: |
 176             Name used when referring to this space in other definitions, not used outside of the spec.
 177           type: string
 178         name-prefix:
 179           description: |
 180             Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
 181           type: string
 182         enum-name:
 183           description: Name for the enum type of the attribute.
 184           type: string
 185         doc:
 186           description: Documentation of the space.
 187           type: string
 188         subset-of:
 189           description: |
 190             Name of another space which this is a logical part of. Sub-spaces can be used to define
 191             a limited group of attributes which are used in a nest.
 192           type: string
 193         # Start genetlink-c
 194         attr-cnt-name:
 195           description: The explicit name for constant holding the count of attributes (last attr + 1).
 196           type: string
 197         attr-max-name:
 198           description: The explicit name for last member of attribute enum.
 199           type: string
 200         # End genetlink-c
 201         attributes:
 202           description: List of attributes in the space.
 203           type: array
 204           items:
 205             type: object
 206             required: [ name ]
 207             additionalProperties: False
 208             properties:
 209               name:
 210                 type: string
 211               type: &attr-type
 212                 description: The netlink attribute type
 213                 enum: [ unused, pad, flag, binary, bitfield32,
 214                         u8, u16, u32, u64, s8, s16, s32, s64,
 215                         string, nest, array-nest, nest-type-value,
 216                         sub-message ]
 217               doc:
 218                 description: Documentation of the attribute.
 219                 type: string
 220               value:
 221                 description: Value for the enum item representing this attribute in the uAPI.
 222                 $ref: '#/$defs/uint'
 223               type-value:
 224                 description: Name of the value extracted from the type of a nest-type-value attribute.
 225                 type: array
 226                 items:
 227                   type: string
 228               byte-order:
 229                 enum: [ little-endian, big-endian ]
 230               multi-attr:
 231                 type: boolean
 232               nested-attributes:
 233                 description: Name of the space (sub-space) used inside the attribute.
 234                 type: string
 235               enum:
 236                 description: Name of the enum type used for the attribute.
 237                 type: string
 238               enum-as-flags:
 239                 description: |
 240                   Treat the enum as flags. In most cases enum is either used as flags or as values.
 241                   Sometimes, however, both forms are necessary, in which case header contains the enum
 242                   form while specific attributes may request to convert the values into a bitfield.
 243                 type: boolean
 244               checks:
 245                 description: Kernel input validation.
 246                 type: object
 247                 additionalProperties: False
 248                 properties:
 249                   flags-mask:
 250                     description: Name of the flags constant on which to base mask (unsigned scalar types only).
 251                     type: string
 252                   min:
 253                     description: Min value for an integer attribute.
 254                     type: integer
 255                   min-len:
 256                     description: Min length for a binary attribute.
 257                     $ref: '#/$defs/len-or-define'
 258                   max-len:
 259                     description: Max length for a string or a binary attribute.
 260                     $ref: '#/$defs/len-or-define'
 261                   exact-len:
 262                     description: Exact length for a string or a binary attribute.
 263                     $ref: '#/$defs/len-or-define'
 264               sub-type: *attr-type
 265               display-hint: *display-hint
 266               # Start genetlink-c
 267               name-prefix:
 268                 type: string
 269               # End genetlink-c
 270               # Start genetlink-legacy
 271               struct:
 272                 description: Name of the struct type used for the attribute.
 273                 type: string
 274               # End genetlink-legacy
 275               # Start netlink-raw
 276               sub-message:
 277                 description: |
 278                   Name of the sub-message definition to use for the attribute.
 279                 type: string
 280               selector:
 281                 description: |
 282                   Name of the attribute to use for dynamic selection of sub-message
 283                   format specifier.
 284                 type: string
 285               # End netlink-raw
 286
 287       # Make sure name-prefix does not appear in subsets (subsets inherit naming)
 288       dependencies:
 289         name-prefix:
 290           not:
 291             required: [ subset-of ]
 292         subset-of:
 293           not:
 294             required: [ name-prefix ]
 295
 296       # type property is only required if not in subset definition
 297       if:
 298         properties:
 299           subset-of:
 300             not:
 301               type: string
 302       then:
 303         properties:
 304           attributes:
 305             items:
 306               required: [ type ]
 307
 308   # Start netlink-raw
 309   sub-messages:
 310     description: Definition of sub message attributes
 311     type: array
 312     items:
 313       type: object
 314       additionalProperties: False
 315       required: [ name, formats ]
 316       properties:
 317         name:
 318           description: Name of the sub-message definition
 319           type: string
 320         formats:
 321           description: Dynamically selected format specifiers
 322           type: array
 323           items:
 324             type: object
 325             additionalProperties: False
 326             required: [ value ]
 327             properties:
 328               value:
 329                 description: |
 330                   Value to match for dynamic selection of sub-message format
 331                   specifier.
 332                 type: string
 333               fixed-header:
 334                 description: |
 335                   Name of the struct definition to use as the fixed header
 336                   for the sub message.
 337                 type: string
 338               attribute-set:
 339                 description: |
 340                   Name of the attribute space from which to resolve attributes
 341                   in the sub message.
 342                 type: string
 343   # End netlink-raw
 344
 345   operations:
 346     description: Operations supported by the protocol.
 347     type: object
 348     required: [ list ]
 349     additionalProperties: False
 350     properties:
 351       enum-model:
 352         description: |
 353           The model of assigning values to the operations.
 354           "unified" is the recommended model where all message types belong
 355           to a single enum.
 356           "directional" has the messages sent to the kernel and from the kernel
 357           enumerated separately.
 358         enum: [ unified, directional ] # Trim
 359       name-prefix:
 360         description: |
 361           Prefix for the C enum name of the command. The name is formed by concatenating
 362           the prefix with the upper case name of the command, with dashes replaced by underscores.
 363         type: string
 364       enum-name:
 365         description: Name for the enum type with commands.
 366         type: string
 367       async-prefix:
 368         description: Same as name-prefix but used to render notifications and events to separate enum.
 369         type: string
 370       async-enum:
 371         description: Name for the enum type with notifications/events.
 372         type: string
 373       # Start genetlink-legacy
 374       fixed-header: &fixed-header
 375         description: |
 376           Name of the structure defining the optional fixed-length protocol
 377           header. This header is placed in a message after the netlink and
 378           genetlink headers and before any attributes.
 379         type: string
 380       # End genetlink-legacy
 381       list:
 382         description: List of commands
 383         type: array
 384         items:
 385           type: object
 386           additionalProperties: False
 387           required: [ name, doc ]
 388           properties:
 389             name:
 390               description: Name of the operation, also defining its C enum value in uAPI.
 391               type: string
 392             doc:
 393               description: Documentation for the command.
 394               type: string
 395             value:
 396               description: Value for the enum in the uAPI.
 397               $ref: '#/$defs/uint'
 398             attribute-set:
 399               description: |
 400                 Attribute space from which attributes directly in the requests and replies
 401                 to this command are defined.
 402               type: string
 403             flags: &cmd_flags
 404               description: Command flags.
 405               type: array
 406               items:
 407                 enum: [ admin-perm ]
 408             dont-validate:
 409               description: Kernel attribute validation flags.
 410               type: array
 411               items:
 412                 enum: [ strict, dump ]
 413             # Start genetlink-legacy
 414             fixed-header: *fixed-header
 415             # End genetlink-legacy
 416             do: &subop-type
 417               description: Main command handler.
 418               type: object
 419               additionalProperties: False
 420               properties:
 421                 request: &subop-attr-list
 422                   description: Definition of the request message for a given command.
 423                   type: object
 424                   additionalProperties: False
 425                   properties:
 426                     attributes:
 427                       description: |
 428                         Names of attributes from the attribute-set (not full attribute
 429                         definitions, just names).
 430                       type: array
 431                       items:
 432                         type: string
 433                     # Start genetlink-legacy
 434                     value:
 435                       description: |
 436                         ID of this message if value for request and response differ,
 437                         i.e. requests and responses have different message enums.
 438                       $ref: '#/$defs/uint'
 439                     # End genetlink-legacy
 440                 reply: *subop-attr-list
 441                 pre:
 442                   description: Hook for a function to run before the main callback (pre_doit or start).
 443                   type: string
 444                 post:
 445                   description: Hook for a function to run after the main callback (post_doit or done).
 446                   type: string
 447             dump: *subop-type
 448             notify:
 449               description: Name of the command sharing the reply type with this notification.
 450               type: string
 451             event:
 452               type: object
 453               additionalProperties: False
 454               properties:
 455                 attributes:
 456                   description: Explicit list of the attributes for the notification.
 457                   type: array
 458                   items:
 459                     type: string
 460             mcgrp:
 461               description: Name of the multicast group generating given notification.
 462               type: string
 463   mcast-groups:
 464     description: List of multicast groups.
 465     type: object
 466     required: [ list ]
 467     additionalProperties: False
 468     properties:
 469       list:
 470         description: List of groups.
 471         type: array
 472         items:
 473           type: object
 474           required: [ name ]
 475           additionalProperties: False
 476           properties:
 477             name:
 478               description: |
 479                 The name for the group, used to form the define and the value of the define.
 480               type: string
 481             # Start genetlink-c
 482             c-define-name:
 483               description: Override for the name of the define in C uAPI.
 484               type: string
 485             # End genetlink-c
 486             flags: *cmd_flags
 487             # Start netlink-raw
 488             value:
 489               description: Value of the netlink multicast group in the uAPI.
 490               type: integer
 491             # End netlink-raw