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