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