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 scope: 73 description: | 74 Visibility of this definition. "uapi" (default) renders into 75 the uAPI header, "kernel" renders into the kernel-side 76 generated header, "user" renders into the user-side 77 generated header. When combined with `header:`, the 78 definition is not rendered, and the named header is 79 included only by code matching the scope. 80 enum: [ uapi, kernel, user ] 81 type: 82 enum: [ const, enum, flags ] 83 doc: 84 type: string 85 # For const 86 value: 87 description: For const - the value. 88 type: [ string, integer ] 89 # For enum and flags 90 value-start: 91 description: For enum or flags the literal initializer for the first value. 92 type: [ string, integer ] 93 entries: 94 description: For enum or flags array of values. 95 type: array 96 items: 97 oneOf: 98 - type: string 99 - type: object 100 required: [ name ] 101 additionalProperties: False 102 properties: 103 name: 104 type: string 105 value: 106 type: integer 107 doc: 108 type: string 109 render-max: 110 description: Render the max members for this enum. 111 type: boolean 112 # Start genetlink-c 113 enum-name: 114 description: Name for enum, if empty no name will be used. 115 type: [ string, "null" ] 116 name-prefix: 117 description: For enum the prefix of the values, optional. 118 type: string 119 enum-cnt-name: 120 description: Name of the render-max counter enum entry. 121 type: string 122 # End genetlink-c 123 124 attribute-sets: 125 description: Definition of attribute spaces for this family. 126 type: array 127 items: 128 description: Definition of a single attribute space. 129 type: object 130 required: [ name, attributes ] 131 additionalProperties: False 132 properties: 133 name: 134 description: | 135 Name used when referring to this space in other definitions, not used outside of the spec. 136 type: string 137 name-prefix: 138 description: | 139 Prefix for the C enum name of the attributes. Default family[name]-set[name]-a- 140 type: string 141 enum-name: 142 description: | 143 Name for the enum type of the attribute, if empty no name will be used. 144 type: [ string, "null" ] 145 doc: 146 description: Documentation of the space. 147 type: string 148 subset-of: 149 description: | 150 Name of another space which this is a logical part of. Sub-spaces can be used to define 151 a limited group of attributes which are used in a nest. 152 type: string 153 # Start genetlink-c 154 attr-cnt-name: 155 description: The explicit name for constant holding the count of attributes (last attr + 1). 156 type: string 157 attr-max-name: 158 description: The explicit name for last member of attribute enum. 159 type: string 160 header: 161 description: For C-compatible languages, header which already defines this attribute set. 162 type: string 163 # End genetlink-c 164 attributes: 165 description: List of attributes in the space. 166 type: array 167 items: 168 type: object 169 required: [ name ] 170 additionalProperties: False 171 properties: 172 name: 173 type: string 174 type: &attr-type 175 enum: [ unused, pad, flag, binary, 176 uint, sint, u8, u16, u32, u64, s8, s16, s32, s64, 177 string, nest, indexed-array, 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 $ref: '#/$defs/len-or-limit' 216 max: 217 description: Max value for an integer attribute. 218 $ref: '#/$defs/len-or-limit' 219 min-len: 220 description: Min length for a binary attribute. 221 $ref: '#/$defs/len-or-define' 222 max-len: 223 description: Max length for a string or a binary attribute. 224 $ref: '#/$defs/len-or-define' 225 exact-len: 226 description: Exact length for a string or a binary attribute. 227 $ref: '#/$defs/len-or-define' 228 unterminated-ok: 229 description: | 230 For string attributes, do not check whether attribute 231 contains the terminating null character. 232 type: boolean 233 sub-type: *attr-type 234 display-hint: &display-hint 235 description: | 236 Optional format indicator that is intended only for choosing 237 the right formatting mechanism when displaying values of this 238 type. 239 enum: [ hex, mac, fddi, ipv4, ipv6, ipv4-or-v6, uuid ] 240 # Start genetlink-c 241 name-prefix: 242 type: string 243 # End genetlink-c 244 245 # Make sure name-prefix does not appear in subsets (subsets inherit naming) 246 dependencies: 247 name-prefix: 248 not: 249 required: [ subset-of ] 250 subset-of: 251 not: 252 required: [ name-prefix ] 253 254 # type property is only required if not in subset definition 255 if: 256 properties: 257 subset-of: 258 not: 259 type: string 260 then: 261 properties: 262 attributes: 263 items: 264 required: [ type ] 265 266 operations: 267 description: Operations supported by the protocol. 268 type: object 269 required: [ list ] 270 additionalProperties: False 271 properties: 272 enum-model: 273 description: | 274 The model of assigning values to the operations. 275 "unified" is the recommended model where all message types belong 276 to a single enum. 277 "directional" has the messages sent to the kernel and from the kernel 278 enumerated separately. 279 enum: [ unified ] 280 name-prefix: 281 description: | 282 Prefix for the C enum name of the command. The name is formed by concatenating 283 the prefix with the upper case name of the command, with dashes replaced by underscores. 284 type: string 285 enum-name: 286 description: | 287 Name for the enum type with commands, if empty no name will be used. 288 type: [ string, "null" ] 289 async-prefix: 290 description: Same as name-prefix but used to render notifications and events to separate enum. 291 type: string 292 async-enum: 293 description: | 294 Name for the enum type with commands, if empty no name will be used. 295 type: [ string, "null" ] 296 list: 297 description: List of commands 298 type: array 299 items: 300 type: object 301 additionalProperties: False 302 required: [ name, doc ] 303 properties: 304 name: 305 description: Name of the operation, also defining its C enum value in uAPI. 306 type: string 307 doc: 308 description: Documentation for the command. 309 type: string 310 value: 311 description: Value for the enum in the uAPI. 312 $ref: '#/$defs/uint' 313 attribute-set: 314 description: | 315 Attribute space from which attributes directly in the requests and replies 316 to this command are defined. 317 type: string 318 flags: &cmd_flags 319 description: Command flags. 320 type: array 321 items: 322 enum: [ admin-perm ] 323 dont-validate: 324 description: Kernel attribute validation flags. 325 type: array 326 items: 327 enum: [ strict, dump, dump-strict ] 328 config-cond: 329 description: | 330 Name of the kernel config option gating the presence of 331 the operation, without the 'CONFIG_' prefix. 332 type: string 333 do: &subop-type 334 description: Main command handler. 335 type: object 336 additionalProperties: False 337 properties: 338 request: &subop-attr-list 339 description: Definition of the request message for a given command. 340 type: object 341 additionalProperties: False 342 properties: 343 attributes: 344 description: | 345 Names of attributes from the attribute-set (not full attribute 346 definitions, just names). 347 type: array 348 items: 349 type: string 350 reply: *subop-attr-list 351 pre: 352 description: Hook for a function to run before the main callback (pre_doit or start). 353 type: string 354 post: 355 description: Hook for a function to run after the main callback (post_doit or done). 356 type: string 357 dump: *subop-type 358 notify: 359 description: Name of the command sharing the reply type with this notification. 360 type: string 361 event: 362 type: object 363 additionalProperties: False 364 properties: 365 attributes: 366 description: Explicit list of the attributes for the notification. 367 type: array 368 items: 369 type: string 370 mcgrp: 371 description: Name of the multicast group generating given notification. 372 type: string 373 mcast-groups: 374 description: List of multicast groups. 375 type: object 376 required: [ list ] 377 additionalProperties: False 378 properties: 379 list: 380 description: List of groups. 381 type: array 382 items: 383 type: object 384 required: [ name ] 385 additionalProperties: False 386 properties: 387 name: 388 description: | 389 The name for the group, used to form the define and the value of the define. 390 type: string 391 # Start genetlink-c 392 c-define-name: 393 description: Override for the name of the define in C uAPI. 394 type: string 395 # End genetlink-c 396 flags: *cmd_flags 397 398 kernel-family: 399 description: Additional global attributes used for kernel C code generation. 400 type: object 401 additionalProperties: False 402 properties: 403 headers: 404 description: | 405 List of extra headers which should be included in the source 406 of the generated code. 407 type: array 408 items: 409 type: string 410 sock-priv: 411 description: | 412 Literal name of the type which is used within the kernel 413 to store the socket state. The type / structure is internal 414 to the kernel, and is not defined in the spec. 415 type: string 416