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