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