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