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: Name for the enum type of the attribute.
 130           type: string
 131         doc:
 132           description: Documentation of the space.
 133           type: string
 134         subset-of:
 135           description: |
 136             Name of another space which this is a logical part of. Sub-spaces can be used to define
 137             a limited group of attributes which are used in a nest.
 138           type: string
 139         # Start genetlink-c
 140         attr-cnt-name:
 141           description: The explicit name for constant holding the count of attributes (last attr + 1).
 142           type: string
 143         attr-max-name:
 144           description: The explicit name for last member of attribute enum.
 145           type: string
 146         # End genetlink-c
 147         attributes:
 148           description: List of attributes in the space.
 149           type: array
 150           items:
 151             type: object
 152             required: [ name ]
 153             additionalProperties: False
 154             properties:
 155               name:
 156                 type: string
 157               type: &attr-type
 158                 enum: [ unused, pad, flag, binary,
 159                         uint, sint, u8, u16, u32, u64, s32, s64,
 160                         string, nest, array-nest, nest-type-value ]
 161               doc:
 162                 description: Documentation of the attribute.
 163                 type: string
 164               value:
 165                 description: Value for the enum item representing this attribute in the uAPI.
 166                 $ref: '#/$defs/uint'
 167               type-value:
 168                 description: Name of the value extracted from the type of a nest-type-value attribute.
 169                 type: array
 170                 items:
 171                   type: string
 172               byte-order:
 173                 enum: [ little-endian, big-endian ]
 174               multi-attr:
 175                 type: boolean
 176               nested-attributes:
 177                 description: Name of the space (sub-space) used inside the attribute.
 178                 type: string
 179               enum:
 180                 description: Name of the enum type used for the attribute.
 181                 type: string
 182               enum-as-flags:
 183                 description: |
 184                   Treat the enum as flags. In most cases enum is either used as flags or as values.
 185                   Sometimes, however, both forms are necessary, in which case header contains the enum
 186                   form while specific attributes may request to convert the values into a bitfield.
 187                 type: boolean
 188               checks:
 189                 description: Kernel input validation.
 190                 type: object
 191                 additionalProperties: False
 192                 properties:
 193                   flags-mask:
 194                     description: Name of the flags constant on which to base mask (unsigned scalar types only).
 195                     type: string
 196                   min:
 197                     description: Min value for an integer attribute.
 198                     $ref: '#/$defs/len-or-limit'
 199                   max:
 200                     description: Max value for an integer attribute.
 201                     $ref: '#/$defs/len-or-limit'
 202                   min-len:
 203                     description: Min length for a binary attribute.
 204                     $ref: '#/$defs/len-or-define'
 205                   max-len:
 206                     description: Max length for a string or a binary attribute.
 207                     $ref: '#/$defs/len-or-define'
 208                   exact-len:
 209                     description: Exact length for a string or a binary attribute.
 210                     $ref: '#/$defs/len-or-define'
 211               sub-type: *attr-type
 212               display-hint: &display-hint
 213                 description: |
 214                   Optional format indicator that is intended only for choosing
 215                   the right formatting mechanism when displaying values of this
 216                   type.
 217                 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
 218               # Start genetlink-c
 219               name-prefix:
 220                 type: string
 221               # End genetlink-c
 222
 223       # Make sure name-prefix does not appear in subsets (subsets inherit naming)
 224       dependencies:
 225         name-prefix:
 226           not:
 227             required: [ subset-of ]
 228         subset-of:
 229           not:
 230             required: [ name-prefix ]
 231
 232       # type property is only required if not in subset definition
 233       if:
 234         properties:
 235           subset-of:
 236             not:
 237               type: string
 238       then:
 239         properties:
 240           attributes:
 241             items:
 242               required: [ type ]
 243
 244   operations:
 245     description: Operations supported by the protocol.
 246     type: object
 247     required: [ list ]
 248     additionalProperties: False
 249     properties:
 250       enum-model:
 251         description: |
 252           The model of assigning values to the operations.
 253           "unified" is the recommended model where all message types belong
 254           to a single enum.
 255           "directional" has the messages sent to the kernel and from the kernel
 256           enumerated separately.
 257         enum: [ unified ]
 258       name-prefix:
 259         description: |
 260           Prefix for the C enum name of the command. The name is formed by concatenating
 261           the prefix with the upper case name of the command, with dashes replaced by underscores.
 262         type: string
 263       enum-name:
 264         description: Name for the enum type with commands.
 265         type: string
 266       async-prefix:
 267         description: Same as name-prefix but used to render notifications and events to separate enum.
 268         type: string
 269       async-enum:
 270         description: Name for the enum type with notifications/events.
 271         type: string
 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, dump-strict ]
 304             config-cond:
 305               description: |
 306                 Name of the kernel config option gating the presence of
 307                 the operation, without the 'CONFIG_' prefix.
 308               type: string
 309             do: &subop-type
 310               description: Main command handler.
 311               type: object
 312               additionalProperties: False
 313               properties:
 314                 request: &subop-attr-list
 315                   description: Definition of the request message for a given command.
 316                   type: object
 317                   additionalProperties: False
 318                   properties:
 319                     attributes:
 320                       description: |
 321                         Names of attributes from the attribute-set (not full attribute
 322                         definitions, just names).
 323                       type: array
 324                       items:
 325                         type: string
 326                 reply: *subop-attr-list
 327                 pre:
 328                   description: Hook for a function to run before the main callback (pre_doit or start).
 329                   type: string
 330                 post:
 331                   description: Hook for a function to run after the main callback (post_doit or done).
 332                   type: string
 333             dump: *subop-type
 334             notify:
 335               description: Name of the command sharing the reply type with this notification.
 336               type: string
 337             event:
 338               type: object
 339               additionalProperties: False
 340               properties:
 341                 attributes:
 342                   description: Explicit list of the attributes for the notification.
 343                   type: array
 344                   items:
 345                     type: string
 346             mcgrp:
 347               description: Name of the multicast group generating given notification.
 348               type: string
 349   mcast-groups:
 350     description: List of multicast groups.
 351     type: object
 352     required: [ list ]
 353     additionalProperties: False
 354     properties:
 355       list:
 356         description: List of groups.
 357         type: array
 358         items:
 359           type: object
 360           required: [ name ]
 361           additionalProperties: False
 362           properties:
 363             name:
 364               description: |
 365                 The name for the group, used to form the define and the value of the define.
 366               type: string
 367             # Start genetlink-c
 368             c-define-name:
 369               description: Override for the name of the define in C uAPI.
 370               type: string
 371             # End genetlink-c
 372             flags: *cmd_flags