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 # End genetlink-c 51 52 definitions: 53 description: List of type and constant definitions (enums, flags, defines). 54 type: array 55 items: 56 type: object 57 required: [ type, name ] 58 additionalProperties: False 59 properties: 60 name: 61 type: string 62 header: 63 description: For C-compatible languages, header which already defines this value. 64 type: string 65 type: 66 enum: [ const, enum, flags ] 67 doc: 68 type: string 69 # For const 70 value: 71 description: For const - the value. 72 type: [ string, integer ] 73 # For enum and flags 74 value-start: 75 description: For enum or flags the literal initializer for the first value. 76 type: [ string, integer ] 77 entries: 78 description: For enum or flags array of values. 79 type: array 80 items: 81 oneOf: 82 - type: string 83 - type: object 84 required: [ name ] 85 additionalProperties: False 86 properties: 87 name: 88 type: string 89 value: 90 type: integer 91 doc: 92 type: string 93 render-max: 94 description: Render the max members for this enum. 95 type: boolean 96 # Start genetlink-c 97 enum-name: 98 description: Name for enum, if empty no name will be used. 99 type: [ string, "null" ] 100 name-prefix: 101 description: For enum the prefix of the values, optional. 102 type: string 103 # End genetlink-c 104 105 attribute-sets: 106 description: Definition of attribute spaces for this family. 107 type: array 108 items: 109 description: Definition of a single attribute space. 110 type: object 111 required: [ name, attributes ] 112 additionalProperties: False 113 properties: 114 name: 115 description: | 116 Name used when referring to this space in other definitions, not used outside of the spec. 117 type: string 118 name-prefix: 119 description: | 120 Prefix for the C enum name of the attributes. Default family[name]-set[name]-a- 121 type: string 122 enum-name: 123 description: Name for the enum type of the attribute. 124 type: string 125 doc: 126 description: Documentation of the space. 127 type: string 128 subset-of: 129 description: | 130 Name of another space which this is a logical part of. Sub-spaces can be used to define 131 a limited group of attributes which are used in a nest. 132 type: string 133 # Start genetlink-c 134 attr-cnt-name: 135 description: The explicit name for constant holding the count of attributes (last attr + 1). 136 type: string 137 attr-max-name: 138 description: The explicit name for last member of attribute enum. 139 type: string 140 # End genetlink-c 141 attributes: 142 description: List of attributes in the space. 143 type: array 144 items: 145 type: object 146 required: [ name ] 147 additionalProperties: False 148 properties: 149 name: 150 type: string 151 type: &attr-type 152 enum: [ unused, pad, flag, binary, 153 uint, sint, u8, u16, u32, u64, s32, s64, 154 string, nest, array-nest, nest-type-value ] 155 doc: 156 description: Documentation of the attribute. 157 type: string 158 value: 159 description: Value for the enum item representing this attribute in the uAPI. 160 $ref: '#/$defs/uint' 161 type-value: 162 description: Name of the value extracted from the type of a nest-type-value attribute. 163 type: array 164 items: 165 type: string 166 byte-order: 167 enum: [ little-endian, big-endian ] 168 multi-attr: 169 type: boolean 170 nested-attributes: 171 description: Name of the space (sub-space) used inside the attribute. 172 type: string 173 enum: 174 description: Name of the enum type used for the attribute. 175 type: string 176 enum-as-flags: 177 description: | 178 Treat the enum as flags. In most cases enum is either used as flags or as values. 179 Sometimes, however, both forms are necessary, in which case header contains the enum 180 form while specific attributes may request to convert the values into a bitfield. 181 type: boolean 182 checks: 183 description: Kernel input validation. 184 type: object 185 additionalProperties: False 186 properties: 187 flags-mask: 188 description: Name of the flags constant on which to base mask (unsigned scalar types only). 189 type: string 190 min: 191 description: Min value for an integer attribute. 192 $ref: '#/$defs/len-or-limit' 193 max: 194 description: Max value for an integer attribute. 195 $ref: '#/$defs/len-or-limit' 196 min-len: 197 description: Min length for a binary attribute. 198 $ref: '#/$defs/len-or-define' 199 max-len: 200 description: Max length for a string or a binary attribute. 201 $ref: '#/$defs/len-or-define' 202 exact-len: 203 description: Exact length for a string or a binary attribute. 204 $ref: '#/$defs/len-or-define' 205 sub-type: *attr-type 206 display-hint: &display-hint 207 description: | 208 Optional format indicator that is intended only for choosing 209 the right formatting mechanism when displaying values of this 210 type. 211 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ] 212 # Start genetlink-c 213 name-prefix: 214 type: string 215 # End genetlink-c 216 217 # Make sure name-prefix does not appear in subsets (subsets inherit naming) 218 dependencies: 219 name-prefix: 220 not: 221 required: [ subset-of ] 222 subset-of: 223 not: 224 required: [ name-prefix ] 225 226 # type property is only required if not in subset definition 227 if: 228 properties: 229 subset-of: 230 not: 231 type: string 232 then: 233 properties: 234 attributes: 235 items: 236 required: [ type ] 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 ] 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 list: 267 description: List of commands 268 type: array 269 items: 270 type: object 271 additionalProperties: False 272 required: [ name, doc ] 273 properties: 274 name: 275 description: Name of the operation, also defining its C enum value in uAPI. 276 type: string 277 doc: 278 description: Documentation for the command. 279 type: string 280 value: 281 description: Value for the enum in the uAPI. 282 $ref: '#/$defs/uint' 283 attribute-set: 284 description: | 285 Attribute space from which attributes directly in the requests and replies 286 to this command are defined. 287 type: string 288 flags: &cmd_flags 289 description: Command flags. 290 type: array 291 items: 292 enum: [ admin-perm ] 293 dont-validate: 294 description: Kernel attribute validation flags. 295 type: array 296 items: 297 enum: [ strict, dump, dump-strict ] 298 config-cond: 299 description: | 300 Name of the kernel config option gating the presence of 301 the operation, without the 'CONFIG_' prefix. 302 type: string 303 do: &subop-type 304 description: Main command handler. 305 type: object 306 additionalProperties: False 307 properties: 308 request: &subop-attr-list 309 description: Definition of the request message for a given command. 310 type: object 311 additionalProperties: False 312 properties: 313 attributes: 314 description: | 315 Names of attributes from the attribute-set (not full attribute 316 definitions, just names). 317 type: array 318 items: 319 type: string 320 reply: *subop-attr-list 321 pre: 322 description: Hook for a function to run before the main callback (pre_doit or start). 323 type: string 324 post: 325 description: Hook for a function to run after the main callback (post_doit or done). 326 type: string 327 dump: *subop-type 328 notify: 329 description: Name of the command sharing the reply type with this notification. 330 type: string 331 event: 332 type: object 333 additionalProperties: False 334 properties: 335 attributes: 336 description: Explicit list of the attributes for the notification. 337 type: array 338 items: 339 type: string 340 mcgrp: 341 description: Name of the multicast group generating given notification. 342 type: string 343 mcast-groups: 344 description: List of multicast groups. 345 type: object 346 required: [ list ] 347 additionalProperties: False 348 properties: 349 list: 350 description: List of groups. 351 type: array 352 items: 353 type: object 354 required: [ name ] 355 additionalProperties: False 356 properties: 357 name: 358 description: | 359 The name for the group, used to form the define and the value of the define. 360 type: string 361 # Start genetlink-c 362 c-define-name: 363 description: Override for the name of the define in C uAPI. 364 type: string 365 # End genetlink-c 366 flags: *cmd_flags 367