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 verion 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, type ] 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 operations: 219 description: Operations supported by the protocol. 220 type: object 221 required: [ list ] 222 additionalProperties: False 223 properties: 224 enum-model: 225 description: | 226 The model of assigning values to the operations. 227 "unified" is the recommended model where all message types belong 228 to a single enum. 229 "directional" has the messages sent to the kernel and from the kernel 230 enumerated separately. 231 enum: [ unified ] 232 name-prefix: 233 description: | 234 Prefix for the C enum name of the command. The name is formed by concatenating 235 the prefix with the upper case name of the command, with dashes replaced by underscores. 236 type: string 237 enum-name: 238 description: Name for the enum type with commands. 239 type: string 240 async-prefix: 241 description: Same as name-prefix but used to render notifications and events to separate enum. 242 type: string 243 async-enum: 244 description: Name for the enum type with notifications/events. 245 type: string 246 list: 247 description: List of commands 248 type: array 249 items: 250 type: object 251 additionalProperties: False 252 required: [ name, doc ] 253 properties: 254 name: 255 description: Name of the operation, also defining its C enum value in uAPI. 256 type: string 257 doc: 258 description: Documentation for the command. 259 type: string 260 value: 261 description: Value for the enum in the uAPI. 262 $ref: '#/$defs/uint' 263 attribute-set: 264 description: | 265 Attribute space from which attributes directly in the requests and replies 266 to this command are defined. 267 type: string 268 flags: &cmd_flags 269 description: Command flags. 270 type: array 271 items: 272 enum: [ admin-perm ] 273 dont-validate: 274 description: Kernel attribute validation flags. 275 type: array 276 items: 277 enum: [ strict, dump ] 278 do: &subop-type 279 description: Main command handler. 280 type: object 281 additionalProperties: False 282 properties: 283 request: &subop-attr-list 284 description: Definition of the request message for a given command. 285 type: object 286 additionalProperties: False 287 properties: 288 attributes: 289 description: | 290 Names of attributes from the attribute-set (not full attribute 291 definitions, just names). 292 type: array 293 items: 294 type: string 295 reply: *subop-attr-list 296 pre: 297 description: Hook for a function to run before the main callback (pre_doit or start). 298 type: string 299 post: 300 description: Hook for a function to run after the main callback (post_doit or done). 301 type: string 302 dump: *subop-type 303 notify: 304 description: Name of the command sharing the reply type with this notification. 305 type: string 306 event: 307 type: object 308 additionalProperties: False 309 properties: 310 attributes: 311 description: Explicit list of the attributes for the notification. 312 type: array 313 items: 314 type: string 315 mcgrp: 316 description: Name of the multicast group generating given notification. 317 type: string 318 mcast-groups: 319 description: List of multicast groups. 320 type: object 321 required: [ list ] 322 additionalProperties: False 323 properties: 324 list: 325 description: List of groups. 326 type: array 327 items: 328 type: object 329 required: [ name ] 330 additionalProperties: False 331 properties: 332 name: 333 description: | 334 The name for the group, used to form the define and the value of the define. 335 type: string 336 # Start genetlink-c 337 c-define-name: 338 description: Override for the name of the define in C uAPI. 339 type: string 340 # End genetlink-c 341 flags: *cmd_flags 342