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