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