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