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 allOf: 180 - 181 if: 182 properties: 183 type: 184 const: pad 185 then: 186 required: [ len ] 187 - 188 if: 189 properties: 190 type: 191 const: binary 192 then: 193 oneOf: 194 - required: [ len ] 195 - required: [ struct ] 196 # End genetlink-legacy 197 198 attribute-sets: 199 description: Definition of attribute spaces for this family. 200 type: array 201 items: 202 description: Definition of a single attribute space. 203 type: object 204 required: [ name, attributes ] 205 additionalProperties: False 206 properties: 207 name: 208 description: | 209 Name used when referring to this space in other definitions, not used outside of the spec. 210 $ref: '#/$defs/name' 211 name-prefix: 212 description: | 213 Prefix for the C enum name of the attributes. Default family[name]-set[name]-a- 214 type: string 215 enum-name: 216 description: | 217 Name for the enum type of the attribute, if empty no name will be used. 218 type: [ string, "null" ] 219 doc: 220 description: Documentation of the space. 221 type: string 222 subset-of: 223 description: | 224 Name of another space which this is a logical part of. Sub-spaces can be used to define 225 a limited group of attributes which are used in a nest. 226 type: string 227 # Start genetlink-c 228 attr-cnt-name: 229 description: The explicit name for constant holding the count of attributes (last attr + 1). 230 type: string 231 attr-max-name: 232 description: The explicit name for last member of attribute enum. 233 type: string 234 header: 235 description: For C-compatible languages, header which already defines this attribute set. 236 type: string 237 # End genetlink-c 238 attributes: 239 description: List of attributes in the space. 240 type: array 241 items: 242 type: object 243 required: [ name ] 244 additionalProperties: False 245 properties: 246 name: 247 $ref: '#/$defs/name' 248 type: &attr-type 249 description: The netlink attribute type 250 enum: [ unused, pad, flag, binary, bitfield32, 251 uint, sint, u8, u16, u32, u64, s8, s16, s32, s64, 252 string, nest, indexed-array, nest-type-value, 253 sub-message ] 254 doc: 255 description: Documentation of the attribute. 256 type: string 257 value: 258 description: Value for the enum item representing this attribute in the uAPI. 259 $ref: '#/$defs/uint' 260 type-value: 261 description: Name of the value extracted from the type of a nest-type-value attribute. 262 type: array 263 items: 264 type: string 265 byte-order: 266 enum: [ little-endian, big-endian ] 267 multi-attr: 268 type: boolean 269 nested-attributes: 270 description: Name of the space (sub-space) used inside the attribute. 271 type: string 272 enum: 273 description: Name of the enum type used for the attribute. 274 type: string 275 enum-as-flags: 276 description: | 277 Treat the enum as flags. In most cases enum is either used as flags or as values. 278 Sometimes, however, both forms are necessary, in which case header contains the enum 279 form while specific attributes may request to convert the values into a bitfield. 280 type: boolean 281 checks: 282 description: Kernel input validation. 283 type: object 284 additionalProperties: False 285 properties: 286 flags-mask: 287 description: Name of the flags constant on which to base mask (unsigned scalar types only). 288 type: string 289 min: 290 description: Min value for an integer attribute. 291 $ref: '#/$defs/len-or-limit' 292 max: 293 description: Max value for an integer attribute. 294 $ref: '#/$defs/len-or-limit' 295 min-len: 296 description: Min length for a binary attribute. 297 $ref: '#/$defs/len-or-define' 298 max-len: 299 description: Max length for a string or a binary attribute. 300 $ref: '#/$defs/len-or-define' 301 exact-len: 302 description: Exact length for a string or a binary attribute. 303 $ref: '#/$defs/len-or-define' 304 unterminated-ok: 305 description: | 306 For string attributes, do not check whether attribute 307 contains the terminating null character. 308 type: boolean 309 sub-type: *attr-type 310 display-hint: *display-hint 311 # Start genetlink-c 312 name-prefix: 313 type: string 314 # End genetlink-c 315 # Start genetlink-legacy 316 struct: 317 description: Name of the struct type used for the attribute. 318 type: string 319 # End genetlink-legacy 320 # Start netlink-raw 321 sub-message: 322 description: | 323 Name of the sub-message definition to use for the attribute. 324 type: string 325 selector: 326 description: | 327 Name of the attribute to use for dynamic selection of sub-message 328 format specifier. 329 type: string 330 # End netlink-raw 331 332 # Make sure name-prefix does not appear in subsets (subsets inherit naming) 333 dependencies: 334 name-prefix: 335 not: 336 required: [ subset-of ] 337 subset-of: 338 not: 339 required: [ name-prefix ] 340 341 # type property is only required if not in subset definition 342 if: 343 properties: 344 subset-of: 345 not: 346 type: string 347 then: 348 properties: 349 attributes: 350 items: 351 required: [ type ] 352 353 # Start netlink-raw 354 sub-messages: 355 description: Definition of sub message attributes 356 type: array 357 items: 358 type: object 359 additionalProperties: False 360 required: [ name, formats ] 361 properties: 362 name: 363 description: Name of the sub-message definition 364 type: string 365 formats: 366 description: Dynamically selected format specifiers 367 type: array 368 items: 369 type: object 370 additionalProperties: False 371 required: [ value ] 372 properties: 373 value: 374 description: | 375 Value to match for dynamic selection of sub-message format 376 specifier. 377 type: string 378 fixed-header: 379 description: | 380 Name of the struct definition to use as the fixed header 381 for the sub message. 382 type: string 383 attribute-set: 384 description: | 385 Name of the attribute space from which to resolve attributes 386 in the sub message. 387 type: string 388 # End netlink-raw 389 390 operations: 391 description: Operations supported by the protocol. 392 type: object 393 required: [ list ] 394 additionalProperties: False 395 properties: 396 enum-model: 397 description: | 398 The model of assigning values to the operations. 399 "unified" is the recommended model where all message types belong 400 to a single enum. 401 "directional" has the messages sent to the kernel and from the kernel 402 enumerated separately. 403 enum: [ unified, directional ] # Trim 404 name-prefix: 405 description: | 406 Prefix for the C enum name of the command. The name is formed by concatenating 407 the prefix with the upper case name of the command, with dashes replaced by underscores. 408 type: string 409 enum-name: 410 description: | 411 Name for the enum type with commands, if empty no name will be used. 412 type: [ string, "null" ] 413 async-prefix: 414 description: Same as name-prefix but used to render notifications and events to separate enum. 415 type: string 416 async-enum: 417 description: | 418 Name for the enum type with commands, if empty no name will be used. 419 type: [ string, "null" ] 420 # Start genetlink-legacy 421 fixed-header: &fixed-header 422 description: | 423 Name of the structure defining the optional fixed-length protocol 424 header. This header is placed in a message after the netlink and 425 genetlink headers and before any attributes. 426 type: string 427 # End genetlink-legacy 428 list: 429 description: List of commands 430 type: array 431 items: 432 type: object 433 additionalProperties: False 434 required: [ name, doc ] 435 properties: 436 name: 437 description: Name of the operation, also defining its C enum value in uAPI. 438 $ref: '#/$defs/name' 439 doc: 440 description: Documentation for the command. 441 type: string 442 value: 443 description: Value for the enum in the uAPI. 444 $ref: '#/$defs/uint' 445 attribute-set: 446 description: | 447 Attribute space from which attributes directly in the requests and replies 448 to this command are defined. 449 type: string 450 flags: &cmd_flags 451 description: Command flags. 452 type: array 453 items: 454 enum: [ admin-perm ] 455 dont-validate: 456 description: Kernel attribute validation flags. 457 type: array 458 items: 459 enum: [ strict, dump ] 460 # Start genetlink-legacy 461 fixed-header: *fixed-header 462 # End genetlink-legacy 463 do: &subop-type 464 description: Main command handler. 465 type: object 466 additionalProperties: False 467 properties: 468 request: &subop-attr-list 469 description: Definition of the request message for a given command. 470 type: object 471 additionalProperties: False 472 properties: 473 attributes: 474 description: | 475 Names of attributes from the attribute-set (not full attribute 476 definitions, just names). 477 type: array 478 items: 479 type: string 480 # Start genetlink-legacy 481 value: 482 description: | 483 ID of this message if value for request and response differ, 484 i.e. requests and responses have different message enums. 485 $ref: '#/$defs/uint' 486 # End genetlink-legacy 487 reply: *subop-attr-list 488 pre: 489 description: Hook for a function to run before the main callback (pre_doit or start). 490 type: string 491 post: 492 description: Hook for a function to run after the main callback (post_doit or done). 493 type: string 494 dump: *subop-type 495 notify: 496 description: Name of the command sharing the reply type with this notification. 497 type: string 498 event: 499 type: object 500 additionalProperties: False 501 properties: 502 attributes: 503 description: Explicit list of the attributes for the notification. 504 type: array 505 items: 506 type: string 507 mcgrp: 508 description: Name of the multicast group generating given notification. 509 type: string 510 mcast-groups: 511 description: List of multicast groups. 512 type: object 513 required: [ list ] 514 additionalProperties: False 515 properties: 516 list: 517 description: List of groups. 518 type: array 519 items: 520 type: object 521 required: [ name ] 522 additionalProperties: False 523 properties: 524 name: 525 description: | 526 The name for the group, used to form the define and the value of the define. 527 type: string 528 # Start genetlink-c 529 c-define-name: 530 description: Override for the name of the define in C uAPI. 531 type: string 532 # End genetlink-c 533 flags: *cmd_flags 534 # Start netlink-raw 535 value: 536 description: Value of the netlink multicast group in the uAPI. 537 type: integer 538 # End netlink-raw 539