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: Name for the enum type of the attribute.
 172           type: string
 173         doc:
 174           description: Documentation of the space.
 175           type: string
 176         subset-of:
 177           description: |
 178             Name of another space which this is a logical part of. Sub-spaces can be used to define
 179             a limited group of attributes which are used in a nest.
 180           type: string
 181         # Start genetlink-c
 182         attr-cnt-name:
 183           description: The explicit name for constant holding the count of attributes (last attr + 1).
 184           type: string
 185         attr-max-name:
 186           description: The explicit name for last member of attribute enum.
 187           type: string
 188         # End genetlink-c
 189         attributes:
 190           description: List of attributes in the space.
 191           type: array
 192           items:
 193             type: object
 194             required: [ name ]
 195             additionalProperties: False
 196             properties:
 197               name:
 198                 type: string
 199               type: &attr-type
 200                 description: The netlink attribute type
 201                 enum: [ unused, pad, flag, binary, bitfield32,
 202                         uint, sint, u8, u16, u32, u64, s32, s64,
 203                         string, nest, array-nest, nest-type-value ]
 204               doc:
 205                 description: Documentation of the attribute.
 206                 type: string
 207               value:
 208                 description: Value for the enum item representing this attribute in the uAPI.
 209                 $ref: '#/$defs/uint'
 210               type-value:
 211                 description: Name of the value extracted from the type of a nest-type-value attribute.
 212                 type: array
 213                 items:
 214                   type: string
 215               byte-order:
 216                 enum: [ little-endian, big-endian ]
 217               multi-attr:
 218                 type: boolean
 219               nested-attributes:
 220                 description: Name of the space (sub-space) used inside the attribute.
 221                 type: string
 222               enum:
 223                 description: Name of the enum type used for the attribute.
 224                 type: string
 225               enum-as-flags:
 226                 description: |
 227                   Treat the enum as flags. In most cases enum is either used as flags or as values.
 228                   Sometimes, however, both forms are necessary, in which case header contains the enum
 229                   form while specific attributes may request to convert the values into a bitfield.
 230                 type: boolean
 231               checks:
 232                 description: Kernel input validation.
 233                 type: object
 234                 additionalProperties: False
 235                 properties:
 236                   flags-mask:
 237                     description: Name of the flags constant on which to base mask (unsigned scalar types only).
 238                     type: string
 239                   min:
 240                     description: Min value for an integer attribute.
 241                     $ref: '#/$defs/len-or-limit'
 242                   max:
 243                     description: Max value for an integer attribute.
 244                     $ref: '#/$defs/len-or-limit'
 245                   min-len:
 246                     description: Min length for a binary attribute.
 247                     $ref: '#/$defs/len-or-define'
 248                   max-len:
 249                     description: Max length for a string or a binary attribute.
 250                     $ref: '#/$defs/len-or-define'
 251                   exact-len:
 252                     description: Exact length for a string or a binary attribute.
 253                     $ref: '#/$defs/len-or-define'
 254               sub-type: *attr-type
 255               display-hint: *display-hint
 256               # Start genetlink-c
 257               name-prefix:
 258                 type: string
 259               # End genetlink-c
 260               # Start genetlink-legacy
 261               struct:
 262                 description: Name of the struct type used for the attribute.
 263                 type: string
 264               # End genetlink-legacy
 265
 266       # Make sure name-prefix does not appear in subsets (subsets inherit naming)
 267       dependencies:
 268         name-prefix:
 269           not:
 270             required: [ subset-of ]
 271         subset-of:
 272           not:
 273             required: [ name-prefix ]
 274
 275       # type property is only required if not in subset definition
 276       if:
 277         properties:
 278           subset-of:
 279             not:
 280               type: string
 281       then:
 282         properties:
 283           attributes:
 284             items:
 285               required: [ type ]
 286
 287   operations:
 288     description: Operations supported by the protocol.
 289     type: object
 290     required: [ list ]
 291     additionalProperties: False
 292     properties:
 293       enum-model:
 294         description: |
 295           The model of assigning values to the operations.
 296           "unified" is the recommended model where all message types belong
 297           to a single enum.
 298           "directional" has the messages sent to the kernel and from the kernel
 299           enumerated separately.
 300         enum: [ unified, directional ] # Trim
 301       name-prefix:
 302         description: |
 303           Prefix for the C enum name of the command. The name is formed by concatenating
 304           the prefix with the upper case name of the command, with dashes replaced by underscores.
 305         type: string
 306       enum-name:
 307         description: Name for the enum type with commands.
 308         type: string
 309       async-prefix:
 310         description: Same as name-prefix but used to render notifications and events to separate enum.
 311         type: string
 312       async-enum:
 313         description: Name for the enum type with notifications/events.
 314         type: string
 315       # Start genetlink-legacy
 316       fixed-header: &fixed-header
 317         description: |
 318           Name of the structure defining the optional fixed-length protocol
 319           header. This header is placed in a message after the netlink and
 320           genetlink headers and before any attributes.
 321         type: string
 322       # End genetlink-legacy
 323       list:
 324         description: List of commands
 325         type: array
 326         items:
 327           type: object
 328           additionalProperties: False
 329           required: [ name, doc ]
 330           properties:
 331             name:
 332               description: Name of the operation, also defining its C enum value in uAPI.
 333               type: string
 334             doc:
 335               description: Documentation for the command.
 336               type: string
 337             value:
 338               description: Value for the enum in the uAPI.
 339               $ref: '#/$defs/uint'
 340             attribute-set:
 341               description: |
 342                 Attribute space from which attributes directly in the requests and replies
 343                 to this command are defined.
 344               type: string
 345             flags: &cmd_flags
 346               description: Command flags.
 347               type: array
 348               items:
 349                 enum: [ admin-perm, uns-admin-perm ]
 350             dont-validate:
 351               description: Kernel attribute validation flags.
 352               type: array
 353               items:
 354                 enum: [ strict, dump, dump-strict ]
 355             config-cond:
 356               description: |
 357                 Name of the kernel config option gating the presence of
 358                 the operation, without the 'CONFIG_' prefix.
 359               type: string
 360             # Start genetlink-legacy
 361             fixed-header: *fixed-header
 362             # End genetlink-legacy
 363             do: &subop-type
 364               description: Main command handler.
 365               type: object
 366               additionalProperties: False
 367               properties:
 368                 request: &subop-attr-list
 369                   description: Definition of the request message for a given command.
 370                   type: object
 371                   additionalProperties: False
 372                   properties:
 373                     attributes:
 374                       description: |
 375                         Names of attributes from the attribute-set (not full attribute
 376                         definitions, just names).
 377                       type: array
 378                       items:
 379                         type: string
 380                     # Start genetlink-legacy
 381                     value:
 382                       description: |
 383                         ID of this message if value for request and response differ,
 384                         i.e. requests and responses have different message enums.
 385                       $ref: '#/$defs/uint'
 386                     # End genetlink-legacy
 387                 reply: *subop-attr-list
 388                 pre:
 389                   description: Hook for a function to run before the main callback (pre_doit or start).
 390                   type: string
 391                 post:
 392                   description: Hook for a function to run after the main callback (post_doit or done).
 393                   type: string
 394             dump: *subop-type
 395             notify:
 396               description: Name of the command sharing the reply type with this notification.
 397               type: string
 398             event:
 399               type: object
 400               additionalProperties: False
 401               properties:
 402                 attributes:
 403                   description: Explicit list of the attributes for the notification.
 404                   type: array
 405                   items:
 406                     type: string
 407             mcgrp:
 408               description: Name of the multicast group generating given notification.
 409               type: string
 410   mcast-groups:
 411     description: List of multicast groups.
 412     type: object
 413     required: [ list ]
 414     additionalProperties: False
 415     properties:
 416       list:
 417         description: List of groups.
 418         type: array
 419         items:
 420           type: object
 421           required: [ name ]
 422           additionalProperties: False
 423           properties:
 424             name:
 425               description: |
 426                 The name for the group, used to form the define and the value of the define.
 427               type: string
 428             # Start genetlink-c
 429             c-define-name:
 430               description: Override for the name of the define in C uAPI.
 431               type: string
 432             # End genetlink-c
 433             flags: *cmd_flags