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