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