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