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 version: 30 description: Generic Netlink family version. Default is 1. 31 type: integer 32 minimum: 1 33 protocol: 34 description: Schema compatibility level. Default is "genetlink". 35 enum: [ genetlink, genetlink-c, genetlink-legacy ] # Trim 36 uapi-header: 37 description: Path to the uAPI header, default is linux/${family-name}.h 38 type: string 39 # Start genetlink-c 40 c-family-name: 41 description: Name of the define for the family name. 42 type: string 43 c-version-name: 44 description: Name of the define for the verion of the family. 45 type: string 46 max-by-define: 47 description: Makes the number of attributes and commands be specified by a define, not an enum value. 48 type: boolean 49 # End genetlink-c 50 # Start genetlink-legacy 51 kernel-policy: 52 description: | 53 Defines if the input policy in the kernel is global, per-operation, or split per operation type. 54 Default is split. 55 enum: [ split, per-op, global ] 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 enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string ] 123 len: 124 $ref: '#/$defs/len-or-define' 125 byte-order: 126 enum: [ little-endian, big-endian ] 127 # End genetlink-legacy 128 129 attribute-sets: 130 description: Definition of attribute spaces for this family. 131 type: array 132 items: 133 description: Definition of a single attribute space. 134 type: object 135 required: [ name, attributes ] 136 additionalProperties: False 137 properties: 138 name: 139 description: | 140 Name used when referring to this space in other definitions, not used outside of the spec. 141 type: string 142 name-prefix: 143 description: | 144 Prefix for the C enum name of the attributes. Default family[name]-set[name]-a- 145 type: string 146 enum-name: 147 description: Name for the enum type of the attribute. 148 type: string 149 doc: 150 description: Documentation of the space. 151 type: string 152 subset-of: 153 description: | 154 Name of another space which this is a logical part of. Sub-spaces can be used to define 155 a limited group of attributes which are used in a nest. 156 type: string 157 # Start genetlink-c 158 attr-cnt-name: 159 description: The explicit name for constant holding the count of attributes (last attr + 1). 160 type: string 161 attr-max-name: 162 description: The explicit name for last member of attribute enum. 163 type: string 164 # End genetlink-c 165 attributes: 166 description: List of attributes in the space. 167 type: array 168 items: 169 type: object 170 required: [ name, type ] 171 additionalProperties: False 172 properties: 173 name: 174 type: string 175 type: &attr-type 176 enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64, 177 string, nest, array-nest, nest-type-value ] 178 doc: 179 description: Documentation of the attribute. 180 type: string 181 value: 182 description: Value for the enum item representing this attribute in the uAPI. 183 $ref: '#/$defs/uint' 184 type-value: 185 description: Name of the value extracted from the type of a nest-type-value attribute. 186 type: array 187 items: 188 type: string 189 byte-order: 190 enum: [ little-endian, big-endian ] 191 multi-attr: 192 type: boolean 193 nested-attributes: 194 description: Name of the space (sub-space) used inside the attribute. 195 type: string 196 enum: 197 description: Name of the enum type used for the attribute. 198 type: string 199 enum-as-flags: 200 description: | 201 Treat the enum as flags. In most cases enum is either used as flags or as values. 202 Sometimes, however, both forms are necessary, in which case header contains the enum 203 form while specific attributes may request to convert the values into a bitfield. 204 type: boolean 205 checks: 206 description: Kernel input validation. 207 type: object 208 additionalProperties: False 209 properties: 210 flags-mask: 211 description: Name of the flags constant on which to base mask (unsigned scalar types only). 212 type: string 213 min: 214 description: Min value for an integer attribute. 215 type: integer 216 min-len: 217 description: Min length for a binary attribute. 218 $ref: '#/$defs/len-or-define' 219 max-len: 220 description: Max length for a string or a binary attribute. 221 $ref: '#/$defs/len-or-define' 222 sub-type: *attr-type 223 # Start genetlink-legacy 224 struct: 225 description: Name of the struct type used for the attribute. 226 type: string 227 # End genetlink-legacy 228 229 # Make sure name-prefix does not appear in subsets (subsets inherit naming) 230 dependencies: 231 name-prefix: 232 not: 233 required: [ subset-of ] 234 subset-of: 235 not: 236 required: [ name-prefix ] 237 238 operations: 239 description: Operations supported by the protocol. 240 type: object 241 required: [ list ] 242 additionalProperties: False 243 properties: 244 enum-model: 245 description: | 246 The model of assigning values to the operations. 247 "unified" is the recommended model where all message types belong 248 to a single enum. 249 "directional" has the messages sent to the kernel and from the kernel 250 enumerated separately. 251 enum: [ unified, directional ] # Trim 252 name-prefix: 253 description: | 254 Prefix for the C enum name of the command. The name is formed by concatenating 255 the prefix with the upper case name of the command, with dashes replaced by underscores. 256 type: string 257 enum-name: 258 description: Name for the enum type with commands. 259 type: string 260 async-prefix: 261 description: Same as name-prefix but used to render notifications and events to separate enum. 262 type: string 263 async-enum: 264 description: Name for the enum type with notifications/events. 265 type: string 266 # Start genetlink-legacy 267 fixed-header: &fixed-header 268 description: | 269 Name of the structure defining the optional fixed-length protocol 270 header. This header is placed in a message after the netlink and 271 genetlink headers and before any attributes. 272 type: string 273 # End genetlink-legacy 274 list: 275 description: List of commands 276 type: array 277 items: 278 type: object 279 additionalProperties: False 280 required: [ name, doc ] 281 properties: 282 name: 283 description: Name of the operation, also defining its C enum value in uAPI. 284 type: string 285 doc: 286 description: Documentation for the command. 287 type: string 288 value: 289 description: Value for the enum in the uAPI. 290 $ref: '#/$defs/uint' 291 attribute-set: 292 description: | 293 Attribute space from which attributes directly in the requests and replies 294 to this command are defined. 295 type: string 296 flags: &cmd_flags 297 description: Command flags. 298 type: array 299 items: 300 enum: [ admin-perm ] 301 dont-validate: 302 description: Kernel attribute validation flags. 303 type: array 304 items: 305 enum: [ strict, dump ] 306 # Start genetlink-legacy 307 fixed-header: *fixed-header 308 # End genetlink-legacy 309 do: &subop-type 310 description: Main command handler. 311 type: object 312 additionalProperties: False 313 properties: 314 request: &subop-attr-list 315 description: Definition of the request message for a given command. 316 type: object 317 additionalProperties: False 318 properties: 319 attributes: 320 description: | 321 Names of attributes from the attribute-set (not full attribute 322 definitions, just names). 323 type: array 324 items: 325 type: string 326 # Start genetlink-legacy 327 value: 328 description: | 329 ID of this message if value for request and response differ, 330 i.e. requests and responses have different message enums. 331 $ref: '#/$defs/uint' 332 # End genetlink-legacy 333 reply: *subop-attr-list 334 pre: 335 description: Hook for a function to run before the main callback (pre_doit or start). 336 type: string 337 post: 338 description: Hook for a function to run after the main callback (post_doit or done). 339 type: string 340 dump: *subop-type 341 notify: 342 description: Name of the command sharing the reply type with this notification. 343 type: string 344 event: 345 type: object 346 additionalProperties: False 347 properties: 348 attributes: 349 description: Explicit list of the attributes for the notification. 350 type: array 351 items: 352 type: string 353 mcgrp: 354 description: Name of the multicast group generating given notification. 355 type: string 356 mcast-groups: 357 description: List of multicast groups. 358 type: object 359 required: [ list ] 360 additionalProperties: False 361 properties: 362 list: 363 description: List of groups. 364 type: array 365 items: 366 type: object 367 required: [ name ] 368 additionalProperties: False 369 properties: 370 name: 371 description: | 372 The name for the group, used to form the define and the value of the define. 373 type: string 374 # Start genetlink-c 375 c-define-name: 376 description: Override for the name of the define in C uAPI. 377 type: string 378 # End genetlink-c 379 flags: *cmd_flags 380