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