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 type: 87 enum: [ const, enum, flags, struct ] # Trim 88 doc: 89 type: string 90 # For const 91 value: 92 description: For const - the value. 93 type: [ string, integer ] 94 # For enum and flags 95 value-start: 96 description: For enum or flags the literal initializer for the first value. 97 type: [ string, integer ] 98 entries: 99 description: For enum or flags array of values. 100 type: array 101 items: 102 oneOf: 103 - type: string 104 - type: object 105 required: [ name ] 106 additionalProperties: False 107 properties: 108 name: 109 $ref: '#/$defs/name' 110 value: 111 type: integer 112 doc: 113 type: string 114 render-max: 115 description: Render the max members for this enum. 116 type: boolean 117 # Start genetlink-c 118 enum-name: 119 description: Name for enum, if empty no name will be used. 120 type: [ string, "null" ] 121 name-prefix: 122 description: For enum the prefix of the values, optional. 123 type: string 124 enum-cnt-name: 125 description: Name of the render-max counter enum entry. 126 type: string 127 # End genetlink-c 128 # Start genetlink-legacy 129 members: 130 description: List of struct members. Only scalars and strings members allowed. 131 type: array 132 items: 133 type: object 134 required: [ name, type ] 135 additionalProperties: False 136 properties: 137 name: 138 $ref: '#/$defs/name' 139 type: 140 description: The netlink attribute type 141 enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ] 142 len: 143 $ref: '#/$defs/len-or-define' 144 byte-order: 145 enum: [ little-endian, big-endian ] 146 doc: 147 description: Documentation for the struct member attribute. 148 type: string 149 enum: 150 description: Name of the enum type used for the attribute. 151 type: string 152 display-hint: &display-hint 153 description: | 154 Optional format indicator that is intended only for choosing 155 the right formatting mechanism when displaying values of this 156 type. 157 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ] 158 struct: 159 description: Name of the nested struct type. 160 type: string 161 # End genetlink-legacy 162 163 attribute-sets: 164 description: Definition of attribute spaces for this family. 165 type: array 166 items: 167 description: Definition of a single attribute space. 168 type: object 169 required: [ name, attributes ] 170 additionalProperties: False 171 properties: 172 name: 173 description: | 174 Name used when referring to this space in other definitions, not used outside of the spec. 175 $ref: '#/$defs/name' 176 name-prefix: 177 description: | 178 Prefix for the C enum name of the attributes. Default family[name]-set[name]-a- 179 type: string 180 enum-name: 181 description: | 182 Name for the enum type of the attribute, if empty no name will be used. 183 type: [ string, "null" ] 184 doc: 185 description: Documentation of the space. 186 type: string 187 subset-of: 188 description: | 189 Name of another space which this is a logical part of. Sub-spaces can be used to define 190 a limited group of attributes which are used in a nest. 191 type: string 192 # Start genetlink-c 193 attr-cnt-name: 194 description: The explicit name for constant holding the count of attributes (last attr + 1). 195 type: string 196 attr-max-name: 197 description: The explicit name for last member of attribute enum. 198 type: string 199 header: 200 description: For C-compatible languages, header which already defines this attribute set. 201 type: string 202 # End genetlink-c 203 attributes: 204 description: List of attributes in the space. 205 type: array 206 items: 207 type: object 208 required: [ name ] 209 additionalProperties: False 210 properties: 211 name: 212 $ref: '#/$defs/name' 213 type: &attr-type 214 description: The netlink attribute type 215 enum: [ unused, pad, flag, binary, bitfield32, 216 uint, sint, u8, u16, u32, u64, s8, s16, s32, s64, 217 string, nest, indexed-array, nest-type-value ] 218 doc: 219 description: Documentation of the attribute. 220 type: string 221 value: 222 description: Value for the enum item representing this attribute in the uAPI. 223 $ref: '#/$defs/uint' 224 type-value: 225 description: Name of the value extracted from the type of a nest-type-value attribute. 226 type: array 227 items: 228 type: string 229 byte-order: 230 enum: [ little-endian, big-endian ] 231 multi-attr: 232 type: boolean 233 nested-attributes: 234 description: Name of the space (sub-space) used inside the attribute. 235 type: string 236 enum: 237 description: Name of the enum type used for the attribute. 238 type: string 239 enum-as-flags: 240 description: | 241 Treat the enum as flags. In most cases enum is either used as flags or as values. 242 Sometimes, however, both forms are necessary, in which case header contains the enum 243 form while specific attributes may request to convert the values into a bitfield. 244 type: boolean 245 checks: 246 description: Kernel input validation. 247 type: object 248 additionalProperties: False 249 properties: 250 flags-mask: 251 description: Name of the flags constant on which to base mask (unsigned scalar types only). 252 type: string 253 min: 254 description: Min value for an integer attribute. 255 $ref: '#/$defs/len-or-limit' 256 max: 257 description: Max value for an integer attribute. 258 $ref: '#/$defs/len-or-limit' 259 min-len: 260 description: Min length for a binary attribute. 261 $ref: '#/$defs/len-or-define' 262 max-len: 263 description: Max length for a string or a binary attribute. 264 $ref: '#/$defs/len-or-define' 265 exact-len: 266 description: Exact length for a string or a binary attribute. 267 $ref: '#/$defs/len-or-define' 268 unterminated-ok: 269 description: | 270 For string attributes, do not check whether attribute 271 contains the terminating null character. 272 type: boolean 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 285 # Make sure name-prefix does not appear in subsets (subsets inherit naming) 286 dependencies: 287 name-prefix: 288 not: 289 required: [ subset-of ] 290 subset-of: 291 not: 292 required: [ name-prefix ] 293 294 # type property is only required if not in subset definition 295 if: 296 properties: 297 subset-of: 298 not: 299 type: string 300 then: 301 properties: 302 attributes: 303 items: 304 required: [ type ] 305 306 operations: 307 description: Operations supported by the protocol. 308 type: object 309 required: [ list ] 310 additionalProperties: False 311 properties: 312 enum-model: 313 description: | 314 The model of assigning values to the operations. 315 "unified" is the recommended model where all message types belong 316 to a single enum. 317 "directional" has the messages sent to the kernel and from the kernel 318 enumerated separately. 319 enum: [ unified, directional ] # Trim 320 name-prefix: 321 description: | 322 Prefix for the C enum name of the command. The name is formed by concatenating 323 the prefix with the upper case name of the command, with dashes replaced by underscores. 324 type: string 325 enum-name: 326 description: | 327 Name for the enum type with commands, if empty no name will be used. 328 type: [ string, "null" ] 329 async-prefix: 330 description: Same as name-prefix but used to render notifications and events to separate enum. 331 type: string 332 async-enum: 333 description: | 334 Name for the enum type with commands, if empty no name will be used. 335 type: [ string, "null" ] 336 # Start genetlink-legacy 337 fixed-header: &fixed-header 338 description: | 339 Name of the structure defining the optional fixed-length protocol 340 header. This header is placed in a message after the netlink and 341 genetlink headers and before any attributes. 342 type: string 343 # End genetlink-legacy 344 list: 345 description: List of commands 346 type: array 347 items: 348 type: object 349 additionalProperties: False 350 required: [ name, doc ] 351 properties: 352 name: 353 description: Name of the operation, also defining its C enum value in uAPI. 354 $ref: '#/$defs/name' 355 doc: 356 description: Documentation for the command. 357 type: string 358 value: 359 description: Value for the enum in the uAPI. 360 $ref: '#/$defs/uint' 361 attribute-set: 362 description: | 363 Attribute space from which attributes directly in the requests and replies 364 to this command are defined. 365 type: string 366 flags: &cmd_flags 367 description: Command flags. 368 type: array 369 items: 370 enum: [ admin-perm, uns-admin-perm ] 371 dont-validate: 372 description: Kernel attribute validation flags. 373 type: array 374 items: 375 enum: [ strict, dump, dump-strict ] 376 config-cond: 377 description: | 378 Name of the kernel config option gating the presence of 379 the operation, without the 'CONFIG_' prefix. 380 type: string 381 # Start genetlink-legacy 382 fixed-header: *fixed-header 383 # End genetlink-legacy 384 do: &subop-type 385 description: Main command handler. 386 type: object 387 additionalProperties: False 388 properties: 389 request: &subop-attr-list 390 description: Definition of the request message for a given command. 391 type: object 392 additionalProperties: False 393 properties: 394 attributes: 395 description: | 396 Names of attributes from the attribute-set (not full attribute 397 definitions, just names). 398 type: array 399 items: 400 type: string 401 # Start genetlink-legacy 402 value: 403 description: | 404 ID of this message if value for request and response differ, 405 i.e. requests and responses have different message enums. 406 $ref: '#/$defs/uint' 407 # End genetlink-legacy 408 reply: *subop-attr-list 409 pre: 410 description: Hook for a function to run before the main callback (pre_doit or start). 411 type: string 412 post: 413 description: Hook for a function to run after the main callback (post_doit or done). 414 type: string 415 dump: *subop-type 416 notify: 417 description: Name of the command sharing the reply type with this notification. 418 type: string 419 event: 420 type: object 421 additionalProperties: False 422 properties: 423 attributes: 424 description: Explicit list of the attributes for the notification. 425 type: array 426 items: 427 type: string 428 mcgrp: 429 description: Name of the multicast group generating given notification. 430 type: string 431 mcast-groups: 432 description: List of multicast groups. 433 type: object 434 required: [ list ] 435 additionalProperties: False 436 properties: 437 list: 438 description: List of groups. 439 type: array 440 items: 441 type: object 442 required: [ name ] 443 additionalProperties: False 444 properties: 445 name: 446 description: | 447 The name for the group, used to form the define and the value of the define. 448 type: string 449 # Start genetlink-c 450 c-define-name: 451 description: Override for the name of the define in C uAPI. 452 type: string 453 # End genetlink-c 454 flags: *cmd_flags 455 456 kernel-family: 457 description: Additional global attributes used for kernel C code generation. 458 type: object 459 additionalProperties: False 460 properties: 461 headers: 462 description: | 463 List of extra headers which should be included in the source 464 of the generated code. 465 type: array 466 items: 467 type: string 468 sock-priv: 469 description: | 470 Literal name of the type which is used within the kernel 471 to store the socket state. The type / structure is internal 472 to the kernel, and is not defined in the spec. 473 type: string 474