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