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