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