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 version 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               display-hint: &display-hint
 199                 description: |
 200                   Optional format indicator that is intended only for choosing
 201                   the right formatting mechanism when displaying values of this
 202                   type.
 203                 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
 204               # Start genetlink-c
 205               name-prefix:
 206                 type: string
 207               # End genetlink-c
 208
 209       # Make sure name-prefix does not appear in subsets (subsets inherit naming)
 210       dependencies:
 211         name-prefix:
 212           not:
 213             required: [ subset-of ]
 214         subset-of:
 215           not:
 216             required: [ name-prefix ]
 217
 218   operations:
 219     description: Operations supported by the protocol.
 220     type: object
 221     required: [ list ]
 222     additionalProperties: False
 223     properties:
 224       enum-model:
 225         description: |
 226           The model of assigning values to the operations.
 227           "unified" is the recommended model where all message types belong
 228           to a single enum.
 229           "directional" has the messages sent to the kernel and from the kernel
 230           enumerated separately.
 231         enum: [ unified ]
 232       name-prefix:
 233         description: |
 234           Prefix for the C enum name of the command. The name is formed by concatenating
 235           the prefix with the upper case name of the command, with dashes replaced by underscores.
 236         type: string
 237       enum-name:
 238         description: Name for the enum type with commands.
 239         type: string
 240       async-prefix:
 241         description: Same as name-prefix but used to render notifications and events to separate enum.
 242         type: string
 243       async-enum:
 244         description: Name for the enum type with notifications/events.
 245         type: string
 246       list:
 247         description: List of commands
 248         type: array
 249         items:
 250           type: object
 251           additionalProperties: False
 252           required: [ name, doc ]
 253           properties:
 254             name:
 255               description: Name of the operation, also defining its C enum value in uAPI.
 256               type: string
 257             doc:
 258               description: Documentation for the command.
 259               type: string
 260             value:
 261               description: Value for the enum in the uAPI.
 262               $ref: '#/$defs/uint'
 263             attribute-set:
 264               description: |
 265                 Attribute space from which attributes directly in the requests and replies
 266                 to this command are defined.
 267               type: string
 268             flags: &cmd_flags
 269               description: Command flags.
 270               type: array
 271               items:
 272                 enum: [ admin-perm ]
 273             dont-validate:
 274               description: Kernel attribute validation flags.
 275               type: array
 276               items:
 277                 enum: [ strict, dump, dump-strict ]
 278             do: &subop-type
 279               description: Main command handler.
 280               type: object
 281               additionalProperties: False
 282               properties:
 283                 request: &subop-attr-list
 284                   description: Definition of the request message for a given command.
 285                   type: object
 286                   additionalProperties: False
 287                   properties:
 288                     attributes:
 289                       description: |
 290                         Names of attributes from the attribute-set (not full attribute
 291                         definitions, just names).
 292                       type: array
 293                       items:
 294                         type: string
 295                 reply: *subop-attr-list
 296                 pre:
 297                   description: Hook for a function to run before the main callback (pre_doit or start).
 298                   type: string
 299                 post:
 300                   description: Hook for a function to run after the main callback (post_doit or done).
 301                   type: string
 302             dump: *subop-type
 303             notify:
 304               description: Name of the command sharing the reply type with this notification.
 305               type: string
 306             event:
 307               type: object
 308               additionalProperties: False
 309               properties:
 310                 attributes:
 311                   description: Explicit list of the attributes for the notification.
 312                   type: array
 313                   items:
 314                     type: string
 315             mcgrp:
 316               description: Name of the multicast group generating given notification.
 317               type: string
 318   mcast-groups:
 319     description: List of multicast groups.
 320     type: object
 321     required: [ list ]
 322     additionalProperties: False
 323     properties:
 324       list:
 325         description: List of groups.
 326         type: array
 327         items:
 328           type: object
 329           required: [ name ]
 330           additionalProperties: False
 331           properties:
 332             name:
 333               description: |
 334                 The name for the group, used to form the define and the value of the define.
 335               type: string
 336             # Start genetlink-c
 337             c-define-name:
 338               description: Override for the name of the define in C uAPI.
 339               type: string
 340             # End genetlink-c
 341             flags: *cmd_flags