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   len-or-limit:
  17     # literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc.
  18     type: [ string, integer ]
  19     pattern: ^[su](8|16|32|64)-(min|max)$
  20     minimum: 0
  21
  22 # Schema for specs
  23 title: Protocol
  24 description: Specification of a genetlink protocol
  25 type: object
  26 required: [ name, doc, attribute-sets, operations ]
  27 additionalProperties: False
  28 properties:
  29   name:
  30     description: Name of the genetlink family.
  31     type: string
  32   doc:
  33     type: string
  34   protocol:
  35     description: Schema compatibility level. Default is "genetlink".
  36     enum: [ genetlink, genetlink-c, genetlink-legacy ] # Trim
  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   version:
  64     description: Generic Netlink family version. Default is 1.
  65     type: integer
  66     minimum: 1
  67   # End genetlink-legacy
  68
  69   definitions:
  70     description: List of type and constant definitions (enums, flags, defines).
  71     type: array
  72     items:
  73       type: object
  74       required: [ type, name ]
  75       additionalProperties: False
  76       properties:
  77         name:
  78           type: string
  79         header:
  80           description: For C-compatible languages, header which already defines this value.
  81           type: string
  82         type:
  83           enum: [ const, enum, flags, struct ] # Trim
  84         doc:
  85           type: string
  86         # For const
  87         value:
  88           description: For const - the value.
  89           type: [ string, integer ]
  90         # For enum and flags
  91         value-start:
  92           description: For enum or flags the literal initializer for the first value.
  93           type: [ string, integer ]
  94         entries:
  95           description: For enum or flags array of values.
  96           type: array
  97           items:
  98             oneOf:
  99               - type: string
 100               - type: object
 101                 required: [ name ]
 102                 additionalProperties: False
 103                 properties:
 104                   name:
 105                     type: string
 106                   value:
 107                     type: integer
 108                   doc:
 109                     type: string
 110         render-max:
 111           description: Render the max members for this enum.
 112           type: boolean
 113         # Start genetlink-c
 114         enum-name:
 115           description: Name for enum, if empty no name will be used.
 116           type: [ string, "null" ]
 117         name-prefix:
 118           description: For enum the prefix of the values, optional.
 119           type: string
 120         # End genetlink-c
 121         # Start genetlink-legacy
 122         members:
 123           description: List of struct members. Only scalars and strings members allowed.
 124           type: array
 125           items:
 126             type: object
 127             required: [ name, type ]
 128             additionalProperties: False
 129             properties:
 130               name:
 131                 type: string
 132               type:
 133                 description: The netlink attribute type
 134                 enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ]
 135               len:
 136                 $ref: '#/$defs/len-or-define'
 137               byte-order:
 138                 enum: [ little-endian, big-endian ]
 139               doc:
 140                 description: Documentation for the struct member attribute.
 141                 type: string
 142               enum:
 143                 description: Name of the enum type used for the attribute.
 144                 type: string
 145               display-hint: &display-hint
 146                 description: |
 147                   Optional format indicator that is intended only for choosing
 148                   the right formatting mechanism when displaying values of this
 149                   type.
 150                 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
 151         # End genetlink-legacy
 152
 153   attribute-sets:
 154     description: Definition of attribute spaces for this family.
 155     type: array
 156     items:
 157       description: Definition of a single attribute space.
 158       type: object
 159       required: [ name, attributes ]
 160       additionalProperties: False
 161       properties:
 162         name:
 163           description: |
 164             Name used when referring to this space in other definitions, not used outside of the spec.
 165           type: string
 166         name-prefix:
 167           description: |
 168             Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
 169           type: string
 170         enum-name:
 171           description: |
 172             Name for the enum type of the attribute, if empty no name will be used.
 173           type: [ string, "null" ]
 174         doc:
 175           description: Documentation of the space.
 176           type: string
 177         subset-of:
 178           description: |
 179             Name of another space which this is a logical part of. Sub-spaces can be used to define
 180             a limited group of attributes which are used in a nest.
 181           type: string
 182         # Start genetlink-c
 183         attr-cnt-name:
 184           description: The explicit name for constant holding the count of attributes (last attr + 1).
 185           type: string
 186         attr-max-name:
 187           description: The explicit name for last member of attribute enum.
 188           type: string
 189         # End genetlink-c
 190         attributes:
 191           description: List of attributes in the space.
 192           type: array
 193           items:
 194             type: object
 195             required: [ name ]
 196             additionalProperties: False
 197             properties:
 198               name:
 199                 type: string
 200               type: &attr-type
 201                 description: The netlink attribute type
 202                 enum: [ unused, pad, flag, binary, bitfield32,
 203                         uint, sint, 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                     $ref: '#/$defs/len-or-limit'
 243                   max:
 244                     description: Max value for an integer attribute.
 245                     $ref: '#/$defs/len-or-limit'
 246                   min-len:
 247                     description: Min length for a binary attribute.
 248                     $ref: '#/$defs/len-or-define'
 249                   max-len:
 250                     description: Max length for a string or a binary attribute.
 251                     $ref: '#/$defs/len-or-define'
 252                   exact-len:
 253                     description: Exact length for a string or a binary attribute.
 254                     $ref: '#/$defs/len-or-define'
 255                   unterminated-ok:
 256                     description: |
 257                       For string attributes, do not check whether attribute
 258                       contains the terminating null character.
 259                     type: boolean
 260               sub-type: *attr-type
 261               display-hint: *display-hint
 262               # Start genetlink-c
 263               name-prefix:
 264                 type: string
 265               # End genetlink-c
 266               # Start genetlink-legacy
 267               struct:
 268                 description: Name of the struct type used for the attribute.
 269                 type: string
 270               # End genetlink-legacy
 271
 272       # Make sure name-prefix does not appear in subsets (subsets inherit naming)
 273       dependencies:
 274         name-prefix:
 275           not:
 276             required: [ subset-of ]
 277         subset-of:
 278           not:
 279             required: [ name-prefix ]
 280
 281       # type property is only required if not in subset definition
 282       if:
 283         properties:
 284           subset-of:
 285             not:
 286               type: string
 287       then:
 288         properties:
 289           attributes:
 290             items:
 291               required: [ type ]
 292
 293   operations:
 294     description: Operations supported by the protocol.
 295     type: object
 296     required: [ list ]
 297     additionalProperties: False
 298     properties:
 299       enum-model:
 300         description: |
 301           The model of assigning values to the operations.
 302           "unified" is the recommended model where all message types belong
 303           to a single enum.
 304           "directional" has the messages sent to the kernel and from the kernel
 305           enumerated separately.
 306         enum: [ unified, directional ] # Trim
 307       name-prefix:
 308         description: |
 309           Prefix for the C enum name of the command. The name is formed by concatenating
 310           the prefix with the upper case name of the command, with dashes replaced by underscores.
 311         type: string
 312       enum-name:
 313         description: |
 314           Name for the enum type with commands, if empty no name will be used.
 315         type: [ string, "null" ]
 316       async-prefix:
 317         description: Same as name-prefix but used to render notifications and events to separate enum.
 318         type: string
 319       async-enum:
 320         description: |
 321           Name for the enum type with commands, if empty no name will be used.
 322         type: [ string, "null" ]
 323       # Start genetlink-legacy
 324       fixed-header: &fixed-header
 325         description: |
 326           Name of the structure defining the optional fixed-length protocol
 327           header. This header is placed in a message after the netlink and
 328           genetlink headers and before any attributes.
 329         type: string
 330       # End genetlink-legacy
 331       list:
 332         description: List of commands
 333         type: array
 334         items:
 335           type: object
 336           additionalProperties: False
 337           required: [ name, doc ]
 338           properties:
 339             name:
 340               description: Name of the operation, also defining its C enum value in uAPI.
 341               type: string
 342             doc:
 343               description: Documentation for the command.
 344               type: string
 345             value:
 346               description: Value for the enum in the uAPI.
 347               $ref: '#/$defs/uint'
 348             attribute-set:
 349               description: |
 350                 Attribute space from which attributes directly in the requests and replies
 351                 to this command are defined.
 352               type: string
 353             flags: &cmd_flags
 354               description: Command flags.
 355               type: array
 356               items:
 357                 enum: [ admin-perm, uns-admin-perm ]
 358             dont-validate:
 359               description: Kernel attribute validation flags.
 360               type: array
 361               items:
 362                 enum: [ strict, dump, dump-strict ]
 363             config-cond:
 364               description: |
 365                 Name of the kernel config option gating the presence of
 366                 the operation, without the 'CONFIG_' prefix.
 367               type: string
 368             # Start genetlink-legacy
 369             fixed-header: *fixed-header
 370             # End genetlink-legacy
 371             do: &subop-type
 372               description: Main command handler.
 373               type: object
 374               additionalProperties: False
 375               properties:
 376                 request: &subop-attr-list
 377                   description: Definition of the request message for a given command.
 378                   type: object
 379                   additionalProperties: False
 380                   properties:
 381                     attributes:
 382                       description: |
 383                         Names of attributes from the attribute-set (not full attribute
 384                         definitions, just names).
 385                       type: array
 386                       items:
 387                         type: string
 388                     # Start genetlink-legacy
 389                     value:
 390                       description: |
 391                         ID of this message if value for request and response differ,
 392                         i.e. requests and responses have different message enums.
 393                       $ref: '#/$defs/uint'
 394                     # End genetlink-legacy
 395                 reply: *subop-attr-list
 396                 pre:
 397                   description: Hook for a function to run before the main callback (pre_doit or start).
 398                   type: string
 399                 post:
 400                   description: Hook for a function to run after the main callback (post_doit or done).
 401                   type: string
 402             dump: *subop-type
 403             notify:
 404               description: Name of the command sharing the reply type with this notification.
 405               type: string
 406             event:
 407               type: object
 408               additionalProperties: False
 409               properties:
 410                 attributes:
 411                   description: Explicit list of the attributes for the notification.
 412                   type: array
 413                   items:
 414                     type: string
 415             mcgrp:
 416               description: Name of the multicast group generating given notification.
 417               type: string
 418   mcast-groups:
 419     description: List of multicast groups.
 420     type: object
 421     required: [ list ]
 422     additionalProperties: False
 423     properties:
 424       list:
 425         description: List of groups.
 426         type: array
 427         items:
 428           type: object
 429           required: [ name ]
 430           additionalProperties: False
 431           properties:
 432             name:
 433               description: |
 434                 The name for the group, used to form the define and the value of the define.
 435               type: string
 436             # Start genetlink-c
 437             c-define-name:
 438               description: Override for the name of the define in C uAPI.
 439               type: string
 440             # End genetlink-c
 441             flags: *cmd_flags
 442
 443   kernel-family:
 444     description: Additional global attributes used for kernel C code generation.
 445     type: object
 446     additionalProperties: False
 447     properties:
 448       headers:
 449         description: |
 450           List of extra headers which should be included in the source
 451           of the generated code.
 452         type: array
 453         items:
 454           type: string
 455       sock-priv:
 456         description: |
 457           Literal name of the type which is used within the kernel
 458           to store the socket state. The type / structure is internal
 459           to the kernel, and is not defined in the spec.
 460         type: string