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/genetlink-legacy.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 uint: 13 type: integer 14 minimum: 0 15 len-or-define: 16 type: [ string, integer ] 17 pattern: ^[0-9A-Za-z_-]+( - 1)?$ 18 minimum: 0 19 len-or-limit: 20 # literal int, const name, or limit based on fixed-width type 21 # e.g. u8-min, u16-max, etc. 22 type: [ string, integer ] 23 pattern: ^[0-9A-Za-z_-]+$ 24 minimum: 0 25 26# Schema for specs 27title: Protocol 28description: Specification of a genetlink protocol 29type: object 30required: [ name, doc, attribute-sets, operations ] 31additionalProperties: False 32properties: 33 name: 34 description: Name of the genetlink family. 35 type: string 36 doc: 37 type: string 38 protocol: 39 description: Schema compatibility level. Default is "genetlink". 40 enum: [ genetlink, genetlink-c, genetlink-legacy ] # Trim 41 uapi-header: 42 description: Path to the uAPI header, default is linux/${family-name}.h 43 type: string 44 # Start genetlink-c 45 c-family-name: 46 description: Name of the define for the family name. 47 type: string 48 c-version-name: 49 description: Name of the define for the version of the family. 50 type: string 51 max-by-define: 52 description: Makes the number of attributes and commands be specified by a define, not an enum value. 53 type: boolean 54 cmd-max-name: 55 description: Name of the define for the last operation in the list. 56 type: string 57 cmd-cnt-name: 58 description: The explicit name for constant holding the count of operations (last operation + 1). 59 type: string 60 # End genetlink-c 61 # Start genetlink-legacy 62 kernel-policy: 63 description: | 64 Defines if the input policy in the kernel is global, per-operation, or split per operation type. 65 Default is split. 66 enum: [ split, per-op, global ] 67 version: 68 description: Generic Netlink family version. Default is 1. 69 type: integer 70 minimum: 1 71 # End genetlink-legacy 72 73 definitions: 74 description: List of type and constant definitions (enums, flags, defines). 75 type: array 76 items: 77 type: object 78 required: [ type, name ] 79 additionalProperties: False 80 properties: 81 name: 82 $ref: '#/$defs/name' 83 header: 84 description: For C-compatible languages, header which already defines this value. 85 type: string 86 scope: 87 description: | 88 Visibility of this definition. "uapi" (default) renders into 89 the uAPI header, "kernel" renders into the kernel-side 90 generated header, "user" renders into the user-side 91 generated header. When combined with `header:`, the 92 definition is not rendered, and the named header is 93 included only by code matching the scope. 94 enum: [ uapi, kernel, user ] 95 type: 96 enum: [ const, enum, flags, struct ] # Trim 97 doc: 98 type: string 99 # For const 100 value: 101 description: For const - the value. 102 type: [ string, integer ] 103 # For enum and flags 104 value-start: 105 description: For enum or flags the literal initializer for the first value. 106 type: [ string, integer ] 107 entries: 108 description: For enum or flags array of values. 109 type: array 110 items: 111 oneOf: 112 - type: string 113 - type: object 114 required: [ name ] 115 additionalProperties: False 116 properties: 117 name: 118 $ref: '#/$defs/name' 119 value: 120 type: integer 121 doc: 122 type: string 123 render-max: 124 description: Render the max members for this enum. 125 type: boolean 126 # Start genetlink-c 127 enum-name: 128 description: Name for enum, if empty no name will be used. 129 type: [ string, "null" ] 130 name-prefix: 131 description: For enum the prefix of the values, optional. 132 type: string 133 enum-cnt-name: 134 description: Name of the render-max counter enum entry. 135 type: string 136 # End genetlink-c 137 # Start genetlink-legacy 138 members: 139 description: List of struct members. Only scalars and strings members allowed. 140 type: array 141 items: 142 type: object 143 required: [ name, type ] 144 additionalProperties: False 145 properties: 146 name: 147 $ref: '#/$defs/name' 148 type: 149 description: The netlink attribute type 150 enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ] 151 len: 152 $ref: '#/$defs/len-or-define' 153 byte-order: 154 enum: [ little-endian, big-endian ] 155 doc: 156 description: Documentation for the struct member attribute. 157 type: string 158 enum: 159 description: Name of the enum type used for the attribute. 160 type: string 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 # End genetlink-legacy 171 172 attribute-sets: 173 description: Definition of attribute spaces for this family. 174 type: array 175 items: 176 description: Definition of a single attribute space. 177 type: object 178 required: [ name, attributes ] 179 additionalProperties: False 180 properties: 181 name: 182 description: | 183 Name used when referring to this space in other definitions, not used outside of the spec. 184 $ref: '#/$defs/name' 185 name-prefix: 186 description: | 187 Prefix for the C enum name of the attributes. Default family[name]-set[name]-a- 188 type: string 189 enum-name: 190 description: | 191 Name for the enum type of the attribute, if empty no name will be used. 192 type: [ string, "null" ] 193 doc: 194 description: Documentation of the space. 195 type: string 196 subset-of: 197 description: | 198 Name of another space which this is a logical part of. Sub-spaces can be used to define 199 a limited group of attributes which are used in a nest. 200 type: string 201 # Start genetlink-c 202 attr-cnt-name: 203 description: The explicit name for constant holding the count of attributes (last attr + 1). 204 type: string 205 attr-max-name: 206 description: The explicit name for last member of attribute enum. 207 type: string 208 header: 209 description: For C-compatible languages, header which already defines this attribute set. 210 type: string 211 # End genetlink-c 212 attributes: 213 description: List of attributes in the space. 214 type: array 215 items: 216 type: object 217 required: [ name ] 218 additionalProperties: False 219 properties: 220 name: 221 $ref: '#/$defs/name' 222 type: &attr-type 223 description: The netlink attribute type 224 enum: [ unused, pad, flag, binary, bitfield32, 225 uint, sint, u8, u16, u32, u64, s8, s16, s32, s64, 226 string, nest, indexed-array, nest-type-value ] 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 $ref: '#/$defs/len-or-limit' 265 max: 266 description: Max value for an integer attribute. 267 $ref: '#/$defs/len-or-limit' 268 min-len: 269 description: Min length for a binary attribute. 270 $ref: '#/$defs/len-or-define' 271 max-len: 272 description: Max length for a string or a binary attribute. 273 $ref: '#/$defs/len-or-define' 274 exact-len: 275 description: Exact length for a string or a binary attribute. 276 $ref: '#/$defs/len-or-define' 277 unterminated-ok: 278 description: | 279 For string attributes, do not check whether attribute 280 contains the terminating null character. 281 type: boolean 282 sub-type: *attr-type 283 display-hint: *display-hint 284 # Start genetlink-c 285 name-prefix: 286 type: string 287 # End genetlink-c 288 # Start genetlink-legacy 289 struct: 290 description: Name of the struct type used for the attribute. 291 type: string 292 # End genetlink-legacy 293 294 # Make sure name-prefix does not appear in subsets (subsets inherit naming) 295 dependencies: 296 name-prefix: 297 not: 298 required: [ subset-of ] 299 subset-of: 300 not: 301 required: [ name-prefix ] 302 303 # type property is only required if not in subset definition 304 if: 305 properties: 306 subset-of: 307 not: 308 type: string 309 then: 310 properties: 311 attributes: 312 items: 313 required: [ type ] 314 315 operations: 316 description: Operations supported by the protocol. 317 type: object 318 required: [ list ] 319 additionalProperties: False 320 properties: 321 enum-model: 322 description: | 323 The model of assigning values to the operations. 324 "unified" is the recommended model where all message types belong 325 to a single enum. 326 "directional" has the messages sent to the kernel and from the kernel 327 enumerated separately. 328 enum: [ unified, directional ] # Trim 329 name-prefix: 330 description: | 331 Prefix for the C enum name of the command. The name is formed by concatenating 332 the prefix with the upper case name of the command, with dashes replaced by underscores. 333 type: string 334 enum-name: 335 description: | 336 Name for the enum type with commands, if empty no name will be used. 337 type: [ string, "null" ] 338 async-prefix: 339 description: Same as name-prefix but used to render notifications and events to separate enum. 340 type: string 341 async-enum: 342 description: | 343 Name for the enum type with commands, if empty no name will be used. 344 type: [ string, "null" ] 345 # Start genetlink-legacy 346 fixed-header: &fixed-header 347 description: | 348 Name of the structure defining the optional fixed-length protocol 349 header. This header is placed in a message after the netlink and 350 genetlink headers and before any attributes. 351 type: string 352 # End genetlink-legacy 353 list: 354 description: List of commands 355 type: array 356 items: 357 type: object 358 additionalProperties: False 359 required: [ name, doc ] 360 properties: 361 name: 362 description: Name of the operation, also defining its C enum value in uAPI. 363 $ref: '#/$defs/name' 364 doc: 365 description: Documentation for the command. 366 type: string 367 value: 368 description: Value for the enum in the uAPI. 369 $ref: '#/$defs/uint' 370 attribute-set: 371 description: | 372 Attribute space from which attributes directly in the requests and replies 373 to this command are defined. 374 type: string 375 flags: &cmd_flags 376 description: Command flags. 377 type: array 378 items: 379 enum: [ admin-perm, uns-admin-perm ] 380 dont-validate: 381 description: Kernel attribute validation flags. 382 type: array 383 items: 384 enum: [ strict, dump, dump-strict ] 385 config-cond: 386 description: | 387 Name of the kernel config option gating the presence of 388 the operation, without the 'CONFIG_' prefix. 389 type: string 390 # Start genetlink-legacy 391 fixed-header: *fixed-header 392 # End genetlink-legacy 393 do: &subop-type 394 description: Main command handler. 395 type: object 396 additionalProperties: False 397 properties: 398 request: &subop-attr-list 399 description: Definition of the request message for a given command. 400 type: object 401 additionalProperties: False 402 properties: 403 attributes: 404 description: | 405 Names of attributes from the attribute-set (not full attribute 406 definitions, just names). 407 type: array 408 items: 409 type: string 410 # Start genetlink-legacy 411 value: 412 description: | 413 ID of this message if value for request and response differ, 414 i.e. requests and responses have different message enums. 415 $ref: '#/$defs/uint' 416 # End genetlink-legacy 417 reply: *subop-attr-list 418 pre: 419 description: Hook for a function to run before the main callback (pre_doit or start). 420 type: string 421 post: 422 description: Hook for a function to run after the main callback (post_doit or done). 423 type: string 424 dump: *subop-type 425 notify: 426 description: Name of the command sharing the reply type with this notification. 427 type: string 428 event: 429 type: object 430 additionalProperties: False 431 properties: 432 attributes: 433 description: Explicit list of the attributes for the notification. 434 type: array 435 items: 436 type: string 437 mcgrp: 438 description: Name of the multicast group generating given notification. 439 type: string 440 mcast-groups: 441 description: List of multicast groups. 442 type: object 443 required: [ list ] 444 additionalProperties: False 445 properties: 446 list: 447 description: List of groups. 448 type: array 449 items: 450 type: object 451 required: [ name ] 452 additionalProperties: False 453 properties: 454 name: 455 description: | 456 The name for the group, used to form the define and the value of the define. 457 type: string 458 # Start genetlink-c 459 c-define-name: 460 description: Override for the name of the define in C uAPI. 461 type: string 462 # End genetlink-c 463 flags: *cmd_flags 464 465 kernel-family: 466 description: Additional global attributes used for kernel C code generation. 467 type: object 468 additionalProperties: False 469 properties: 470 headers: 471 description: | 472 List of extra headers which should be included in the source 473 of the generated code. 474 type: array 475 items: 476 type: string 477 sock-priv: 478 description: | 479 Literal name of the type which is used within the kernel 480 to store the socket state. The type / structure is internal 481 to the kernel, and is not defined in the spec. 482 type: string 483