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