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