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, type ]
 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   operations:
 258     description: Operations supported by the protocol.
 259     type: object
 260     required: [ list ]
 261     additionalProperties: False
 262     properties:
 263       enum-model:
 264         description: |
 265           The model of assigning values to the operations.
 266           "unified" is the recommended model where all message types belong
 267           to a single enum.
 268           "directional" has the messages sent to the kernel and from the kernel
 269           enumerated separately.
 270         enum: [ unified, directional ] # Trim
 271       name-prefix:
 272         description: |
 273           Prefix for the C enum name of the command. The name is formed by concatenating
 274           the prefix with the upper case name of the command, with dashes replaced by underscores.
 275         type: string
 276       enum-name:
 277         description: Name for the enum type with commands.
 278         type: string
 279       async-prefix:
 280         description: Same as name-prefix but used to render notifications and events to separate enum.
 281         type: string
 282       async-enum:
 283         description: Name for the enum type with notifications/events.
 284         type: string
 285       # Start genetlink-legacy
 286       fixed-header: &fixed-header
 287         description: |
 288           Name of the structure defining the optional fixed-length protocol
 289           header. This header is placed in a message after the netlink and
 290           genetlink headers and before any attributes.
 291         type: string
 292       # End genetlink-legacy
 293       list:
 294         description: List of commands
 295         type: array
 296         items:
 297           type: object
 298           additionalProperties: False
 299           required: [ name, doc ]
 300           properties:
 301             name:
 302               description: Name of the operation, also defining its C enum value in uAPI.
 303               type: string
 304             doc:
 305               description: Documentation for the command.
 306               type: string
 307             value:
 308               description: Value for the enum in the uAPI.
 309               $ref: '#/$defs/uint'
 310             attribute-set:
 311               description: |
 312                 Attribute space from which attributes directly in the requests and replies
 313                 to this command are defined.
 314               type: string
 315             flags: &cmd_flags
 316               description: Command flags.
 317               type: array
 318               items:
 319                 enum: [ admin-perm ]
 320             dont-validate:
 321               description: Kernel attribute validation flags.
 322               type: array
 323               items:
 324                 enum: [ strict, dump, dump-strict ]
 325             # Start genetlink-legacy
 326             fixed-header: *fixed-header
 327             # End genetlink-legacy
 328             do: &subop-type
 329               description: Main command handler.
 330               type: object
 331               additionalProperties: False
 332               properties:
 333                 request: &subop-attr-list
 334                   description: Definition of the request message for a given command.
 335                   type: object
 336                   additionalProperties: False
 337                   properties:
 338                     attributes:
 339                       description: |
 340                         Names of attributes from the attribute-set (not full attribute
 341                         definitions, just names).
 342                       type: array
 343                       items:
 344                         type: string
 345                     # Start genetlink-legacy
 346                     value:
 347                       description: |
 348                         ID of this message if value for request and response differ,
 349                         i.e. requests and responses have different message enums.
 350                       $ref: '#/$defs/uint'
 351                     # End genetlink-legacy
 352                 reply: *subop-attr-list
 353                 pre:
 354                   description: Hook for a function to run before the main callback (pre_doit or start).
 355                   type: string
 356                 post:
 357                   description: Hook for a function to run after the main callback (post_doit or done).
 358                   type: string
 359             dump: *subop-type
 360             notify:
 361               description: Name of the command sharing the reply type with this notification.
 362               type: string
 363             event:
 364               type: object
 365               additionalProperties: False
 366               properties:
 367                 attributes:
 368                   description: Explicit list of the attributes for the notification.
 369                   type: array
 370                   items:
 371                     type: string
 372             mcgrp:
 373               description: Name of the multicast group generating given notification.
 374               type: string
 375   mcast-groups:
 376     description: List of multicast groups.
 377     type: object
 378     required: [ list ]
 379     additionalProperties: False
 380     properties:
 381       list:
 382         description: List of groups.
 383         type: array
 384         items:
 385           type: object
 386           required: [ name ]
 387           additionalProperties: False
 388           properties:
 389             name:
 390               description: |
 391                 The name for the group, used to form the define and the value of the define.
 392               type: string
 393             # Start genetlink-c
 394             c-define-name:
 395               description: Override for the name of the define in C uAPI.
 396               type: string
 397             # End genetlink-c
 398             flags: *cmd_flags