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