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