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