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