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