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