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