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