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