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