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