Documentation/netlink/genetlink.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 ]
  37   uapi-header:
  38     description: Path to the uAPI header, default is linux/${family-name}.h
  39     type: string
  40
  41   definitions:
  42     description: List of type and constant definitions (enums, flags, defines).
  43     type: array
  44     items:
  45       type: object
  46       required: [ type, name ]
  47       additionalProperties: False
  48       properties:
  49         name:
  50           type: string
  51         header:
  52           description: For C-compatible languages, header which already defines this value.
  53           type: string
  54         type:
  55           enum: [ const, enum, flags ]
  56         doc:
  57           type: string
  58         # For const
  59         value:
  60           description: For const - the value.
  61           type: [ string, integer ]
  62         # For enum and flags
  63         value-start:
  64           description: For enum or flags the literal initializer for the first value.
  65           type: [ string, integer ]
  66         entries:
  67           description: For enum or flags array of values.
  68           type: array
  69           items:
  70             oneOf:
  71               - type: string
  72               - type: object
  73                 required: [ name ]
  74                 additionalProperties: False
  75                 properties:
  76                   name:
  77                     type: string
  78                   value:
  79                     type: integer
  80                   doc:
  81                     type: string
  82         render-max:
  83           description: Render the max members for this enum.
  84           type: boolean
  85
  86   attribute-sets:
  87     description: Definition of attribute spaces for this family.
  88     type: array
  89     items:
  90       description: Definition of a single attribute space.
  91       type: object
  92       required: [ name, attributes ]
  93       additionalProperties: False
  94       properties:
  95         name:
  96           description: |
  97             Name used when referring to this space in other definitions, not used outside of the spec.
  98           type: string
  99         name-prefix:
 100           description: |
 101             Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
 102           type: string
 103         enum-name:
 104           description: Name for the enum type of the attribute.
 105           type: string
 106         doc:
 107           description: Documentation of the space.
 108           type: string
 109         subset-of:
 110           description: |
 111             Name of another space which this is a logical part of. Sub-spaces can be used to define
 112             a limited group of attributes which are used in a nest.
 113           type: string
 114         attributes:
 115           description: List of attributes in the space.
 116           type: array
 117           items:
 118             type: object
 119             required: [ name ]
 120             additionalProperties: False
 121             properties:
 122               name:
 123                 type: string
 124               type: &attr-type
 125                 enum: [ unused, pad, flag, binary,
 126                         uint, sint, u8, u16, u32, u64, s32, s64,
 127                         string, nest, indexed-array, nest-type-value ]
 128               doc:
 129                 description: Documentation of the attribute.
 130                 type: string
 131               value:
 132                 description: Value for the enum item representing this attribute in the uAPI.
 133                 $ref: '#/$defs/uint'
 134               type-value:
 135                 description: Name of the value extracted from the type of a nest-type-value attribute.
 136                 type: array
 137                 items:
 138                   type: string
 139               byte-order:
 140                 enum: [ little-endian, big-endian ]
 141               multi-attr:
 142                 type: boolean
 143               nested-attributes:
 144                 description: Name of the space (sub-space) used inside the attribute.
 145                 type: string
 146               enum:
 147                 description: Name of the enum type used for the attribute.
 148                 type: string
 149               enum-as-flags:
 150                 description: |
 151                   Treat the enum as flags. In most cases enum is either used as flags or as values.
 152                   Sometimes, however, both forms are necessary, in which case header contains the enum
 153                   form while specific attributes may request to convert the values into a bitfield.
 154                 type: boolean
 155               checks:
 156                 description: Kernel input validation.
 157                 type: object
 158                 additionalProperties: False
 159                 properties:
 160                   flags-mask:
 161                     description: Name of the flags constant on which to base mask (unsigned scalar types only).
 162                     type: string
 163                   min:
 164                     description: Min value for an integer attribute.
 165                     $ref: '#/$defs/len-or-limit'
 166                   max:
 167                     description: Max value for an integer attribute.
 168                     $ref: '#/$defs/len-or-limit'
 169                   min-len:
 170                     description: Min length for a binary attribute.
 171                     $ref: '#/$defs/len-or-define'
 172                   max-len:
 173                     description: Max length for a string or a binary attribute.
 174                     $ref: '#/$defs/len-or-define'
 175                   exact-len:
 176                     description: Exact length for a string or a binary attribute.
 177                     $ref: '#/$defs/len-or-define'
 178               sub-type: *attr-type
 179               display-hint: &display-hint
 180                 description: |
 181                   Optional format indicator that is intended only for choosing
 182                   the right formatting mechanism when displaying values of this
 183                   type.
 184                 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
 185
 186       # Make sure name-prefix does not appear in subsets (subsets inherit naming)
 187       dependencies:
 188         name-prefix:
 189           not:
 190             required: [ subset-of ]
 191         subset-of:
 192           not:
 193             required: [ name-prefix ]
 194
 195       # type property is only required if not in subset definition
 196       if:
 197         properties:
 198           subset-of:
 199             not:
 200               type: string
 201       then:
 202         properties:
 203           attributes:
 204             items:
 205               required: [ type ]
 206
 207   operations:
 208     description: Operations supported by the protocol.
 209     type: object
 210     required: [ list ]
 211     additionalProperties: False
 212     properties:
 213       enum-model:
 214         description: |
 215           The model of assigning values to the operations.
 216           "unified" is the recommended model where all message types belong
 217           to a single enum.
 218           "directional" has the messages sent to the kernel and from the kernel
 219           enumerated separately.
 220         enum: [ unified ]
 221       name-prefix:
 222         description: |
 223           Prefix for the C enum name of the command. The name is formed by concatenating
 224           the prefix with the upper case name of the command, with dashes replaced by underscores.
 225         type: string
 226       enum-name:
 227         description: Name for the enum type with commands.
 228         type: string
 229       async-prefix:
 230         description: Same as name-prefix but used to render notifications and events to separate enum.
 231         type: string
 232       async-enum:
 233         description: Name for the enum type with notifications/events.
 234         type: string
 235       list:
 236         description: List of commands
 237         type: array
 238         items:
 239           type: object
 240           additionalProperties: False
 241           required: [ name, doc ]
 242           properties:
 243             name:
 244               description: Name of the operation, also defining its C enum value in uAPI.
 245               type: string
 246             doc:
 247               description: Documentation for the command.
 248               type: string
 249             value:
 250               description: Value for the enum in the uAPI.
 251               $ref: '#/$defs/uint'
 252             attribute-set:
 253               description: |
 254                 Attribute space from which attributes directly in the requests and replies
 255                 to this command are defined.
 256               type: string
 257             flags: &cmd_flags
 258               description: Command flags.
 259               type: array
 260               items:
 261                 enum: [ admin-perm ]
 262             dont-validate:
 263               description: Kernel attribute validation flags.
 264               type: array
 265               items:
 266                 enum: [ strict, dump, dump-strict ]
 267             config-cond:
 268               description: |
 269                 Name of the kernel config option gating the presence of
 270                 the operation, without the 'CONFIG_' prefix.
 271               type: string
 272             do: &subop-type
 273               description: Main command handler.
 274               type: object
 275               additionalProperties: False
 276               properties:
 277                 request: &subop-attr-list
 278                   description: Definition of the request message for a given command.
 279                   type: object
 280                   additionalProperties: False
 281                   properties:
 282                     attributes:
 283                       description: |
 284                         Names of attributes from the attribute-set (not full attribute
 285                         definitions, just names).
 286                       type: array
 287                       items:
 288                         type: string
 289                 reply: *subop-attr-list
 290                 pre:
 291                   description: Hook for a function to run before the main callback (pre_doit or start).
 292                   type: string
 293                 post:
 294                   description: Hook for a function to run after the main callback (post_doit or done).
 295                   type: string
 296             dump: *subop-type
 297             notify:
 298               description: Name of the command sharing the reply type with this notification.
 299               type: string
 300             event:
 301               type: object
 302               additionalProperties: False
 303               properties:
 304                 attributes:
 305                   description: Explicit list of the attributes for the notification.
 306                   type: array
 307                   items:
 308                     type: string
 309             mcgrp:
 310               description: Name of the multicast group generating given notification.
 311               type: string
 312   mcast-groups:
 313     description: List of multicast groups.
 314     type: object
 315     required: [ list ]
 316     additionalProperties: False
 317     properties:
 318       list:
 319         description: List of groups.
 320         type: array
 321         items:
 322           type: object
 323           required: [ name ]
 324           additionalProperties: False
 325           properties:
 326             name:
 327               description: |
 328                 The name for the group, used to form the define and the value of the define.
 329               type: string
 330             flags: *cmd_flags
 331
 332   kernel-family:
 333     description: Additional global attributes used for kernel C code generation.
 334     type: object
 335     additionalProperties: False
 336     properties:
 337       headers:
 338         description: |
 339           List of extra headers which should be included in the source
 340           of the generated code.
 341         type: array
 342         items:
 343           type: string
 344       sock-priv:
 345         description: |
 346           Literal name of the type which is used within the kernel
 347           to store the socket state. The type / structure is internal
 348           to the kernel, and is not defined in the spec.
 349         type: string