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