461 lines · yaml
1# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)2%YAML 1.23---4$id: http://kernel.org/schemas/netlink/genetlink-legacy.yaml#5$schema: https://json-schema.org/draft-07/schema6 7# Common defines8$defs:9 uint:10 type: integer11 minimum: 012 len-or-define:13 type: [ string, integer ]14 pattern: ^[0-9A-Za-z_-]+( - 1)?$15 minimum: 016 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: 021 22# Schema for specs23title: Protocol24description: Specification of a genetlink protocol25type: object26required: [ name, doc, attribute-sets, operations ]27additionalProperties: False28properties:29 name:30 description: Name of the genetlink family.31 type: string32 doc:33 type: string34 protocol:35 description: Schema compatibility level. Default is "genetlink".36 enum: [ genetlink, genetlink-c, genetlink-legacy ] # Trim37 uapi-header:38 description: Path to the uAPI header, default is linux/${family-name}.h39 type: string40 # Start genetlink-c41 c-family-name:42 description: Name of the define for the family name.43 type: string44 c-version-name:45 description: Name of the define for the version of the family.46 type: string47 max-by-define:48 description: Makes the number of attributes and commands be specified by a define, not an enum value.49 type: boolean50 cmd-max-name:51 description: Name of the define for the last operation in the list.52 type: string53 cmd-cnt-name:54 description: The explicit name for constant holding the count of operations (last operation + 1).55 type: string56 # End genetlink-c57 # Start genetlink-legacy58 kernel-policy:59 description: |60 Defines if the input policy in the kernel is global, per-operation, or split per operation type.61 Default is split.62 enum: [ split, per-op, global ]63 version:64 description: Generic Netlink family version. Default is 1.65 type: integer66 minimum: 167 # End genetlink-legacy68 69 definitions:70 description: List of type and constant definitions (enums, flags, defines).71 type: array72 items:73 type: object74 required: [ type, name ]75 additionalProperties: False76 properties:77 name:78 type: string79 header:80 description: For C-compatible languages, header which already defines this value.81 type: string82 type:83 enum: [ const, enum, flags, struct ] # Trim84 doc:85 type: string86 # For const87 value:88 description: For const - the value.89 type: [ string, integer ]90 # For enum and flags91 value-start:92 description: For enum or flags the literal initializer for the first value.93 type: [ string, integer ]94 entries:95 description: For enum or flags array of values.96 type: array97 items:98 oneOf:99 - type: string100 - type: object101 required: [ name ]102 additionalProperties: False103 properties:104 name:105 type: string106 value:107 type: integer108 doc:109 type: string110 render-max:111 description: Render the max members for this enum.112 type: boolean113 # Start genetlink-c114 enum-name:115 description: Name for enum, if empty no name will be used.116 type: [ string, "null" ]117 name-prefix:118 description: For enum the prefix of the values, optional.119 type: string120 # End genetlink-c121 # Start genetlink-legacy122 members:123 description: List of struct members. Only scalars and strings members allowed.124 type: array125 items:126 type: object127 required: [ name, type ]128 additionalProperties: False129 properties:130 name:131 type: string132 type:133 description: The netlink attribute type134 enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ]135 len:136 $ref: '#/$defs/len-or-define'137 byte-order:138 enum: [ little-endian, big-endian ]139 doc:140 description: Documentation for the struct member attribute.141 type: string142 enum:143 description: Name of the enum type used for the attribute.144 type: string145 display-hint: &display-hint146 description: |147 Optional format indicator that is intended only for choosing148 the right formatting mechanism when displaying values of this149 type.150 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]151 # End genetlink-legacy152 153 attribute-sets:154 description: Definition of attribute spaces for this family.155 type: array156 items:157 description: Definition of a single attribute space.158 type: object159 required: [ name, attributes ]160 additionalProperties: False161 properties:162 name:163 description: |164 Name used when referring to this space in other definitions, not used outside of the spec.165 type: string166 name-prefix:167 description: |168 Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-169 type: string170 enum-name:171 description: |172 Name for the enum type of the attribute, if empty no name will be used.173 type: [ string, "null" ]174 doc:175 description: Documentation of the space.176 type: string177 subset-of:178 description: |179 Name of another space which this is a logical part of. Sub-spaces can be used to define180 a limited group of attributes which are used in a nest.181 type: string182 # Start genetlink-c183 attr-cnt-name:184 description: The explicit name for constant holding the count of attributes (last attr + 1).185 type: string186 attr-max-name:187 description: The explicit name for last member of attribute enum.188 type: string189 # End genetlink-c190 attributes:191 description: List of attributes in the space.192 type: array193 items:194 type: object195 required: [ name ]196 additionalProperties: False197 properties:198 name:199 type: string200 type: &attr-type201 description: The netlink attribute type202 enum: [ unused, pad, flag, binary, bitfield32,203 uint, sint, u8, u16, u32, u64, s32, s64,204 string, nest, indexed-array, nest-type-value ]205 doc:206 description: Documentation of the attribute.207 type: string208 value:209 description: Value for the enum item representing this attribute in the uAPI.210 $ref: '#/$defs/uint'211 type-value:212 description: Name of the value extracted from the type of a nest-type-value attribute.213 type: array214 items:215 type: string216 byte-order:217 enum: [ little-endian, big-endian ]218 multi-attr:219 type: boolean220 nested-attributes:221 description: Name of the space (sub-space) used inside the attribute.222 type: string223 enum:224 description: Name of the enum type used for the attribute.225 type: string226 enum-as-flags:227 description: |228 Treat the enum as flags. In most cases enum is either used as flags or as values.229 Sometimes, however, both forms are necessary, in which case header contains the enum230 form while specific attributes may request to convert the values into a bitfield.231 type: boolean232 checks:233 description: Kernel input validation.234 type: object235 additionalProperties: False236 properties:237 flags-mask:238 description: Name of the flags constant on which to base mask (unsigned scalar types only).239 type: string240 min:241 description: Min value for an integer attribute.242 $ref: '#/$defs/len-or-limit'243 max:244 description: Max value for an integer attribute.245 $ref: '#/$defs/len-or-limit'246 min-len:247 description: Min length for a binary attribute.248 $ref: '#/$defs/len-or-define'249 max-len:250 description: Max length for a string or a binary attribute.251 $ref: '#/$defs/len-or-define'252 exact-len:253 description: Exact length for a string or a binary attribute.254 $ref: '#/$defs/len-or-define'255 unterminated-ok:256 description: |257 For string attributes, do not check whether attribute258 contains the terminating null character.259 type: boolean260 sub-type: *attr-type261 display-hint: *display-hint262 # Start genetlink-c263 name-prefix:264 type: string265 # End genetlink-c266 # Start genetlink-legacy267 struct:268 description: Name of the struct type used for the attribute.269 type: string270 # End genetlink-legacy271 272 # Make sure name-prefix does not appear in subsets (subsets inherit naming)273 dependencies:274 name-prefix:275 not:276 required: [ subset-of ]277 subset-of:278 not:279 required: [ name-prefix ]280 281 # type property is only required if not in subset definition282 if:283 properties:284 subset-of:285 not:286 type: string287 then:288 properties:289 attributes:290 items:291 required: [ type ]292 293 operations:294 description: Operations supported by the protocol.295 type: object296 required: [ list ]297 additionalProperties: False298 properties:299 enum-model:300 description: |301 The model of assigning values to the operations.302 "unified" is the recommended model where all message types belong303 to a single enum.304 "directional" has the messages sent to the kernel and from the kernel305 enumerated separately.306 enum: [ unified, directional ] # Trim307 name-prefix:308 description: |309 Prefix for the C enum name of the command. The name is formed by concatenating310 the prefix with the upper case name of the command, with dashes replaced by underscores.311 type: string312 enum-name:313 description: |314 Name for the enum type with commands, if empty no name will be used.315 type: [ string, "null" ]316 async-prefix:317 description: Same as name-prefix but used to render notifications and events to separate enum.318 type: string319 async-enum:320 description: |321 Name for the enum type with commands, if empty no name will be used.322 type: [ string, "null" ]323 # Start genetlink-legacy324 fixed-header: &fixed-header325 description: |326 Name of the structure defining the optional fixed-length protocol327 header. This header is placed in a message after the netlink and328 genetlink headers and before any attributes.329 type: string330 # End genetlink-legacy331 list:332 description: List of commands333 type: array334 items:335 type: object336 additionalProperties: False337 required: [ name, doc ]338 properties:339 name:340 description: Name of the operation, also defining its C enum value in uAPI.341 type: string342 doc:343 description: Documentation for the command.344 type: string345 value:346 description: Value for the enum in the uAPI.347 $ref: '#/$defs/uint'348 attribute-set:349 description: |350 Attribute space from which attributes directly in the requests and replies351 to this command are defined.352 type: string353 flags: &cmd_flags354 description: Command flags.355 type: array356 items:357 enum: [ admin-perm, uns-admin-perm ]358 dont-validate:359 description: Kernel attribute validation flags.360 type: array361 items:362 enum: [ strict, dump, dump-strict ]363 config-cond:364 description: |365 Name of the kernel config option gating the presence of366 the operation, without the 'CONFIG_' prefix.367 type: string368 # Start genetlink-legacy369 fixed-header: *fixed-header370 # End genetlink-legacy371 do: &subop-type372 description: Main command handler.373 type: object374 additionalProperties: False375 properties:376 request: &subop-attr-list377 description: Definition of the request message for a given command.378 type: object379 additionalProperties: False380 properties:381 attributes:382 description: |383 Names of attributes from the attribute-set (not full attribute384 definitions, just names).385 type: array386 items:387 type: string388 # Start genetlink-legacy389 value:390 description: |391 ID of this message if value for request and response differ,392 i.e. requests and responses have different message enums.393 $ref: '#/$defs/uint'394 # End genetlink-legacy395 reply: *subop-attr-list396 pre:397 description: Hook for a function to run before the main callback (pre_doit or start).398 type: string399 post:400 description: Hook for a function to run after the main callback (post_doit or done).401 type: string402 dump: *subop-type403 notify:404 description: Name of the command sharing the reply type with this notification.405 type: string406 event:407 type: object408 additionalProperties: False409 properties:410 attributes:411 description: Explicit list of the attributes for the notification.412 type: array413 items:414 type: string415 mcgrp:416 description: Name of the multicast group generating given notification.417 type: string418 mcast-groups:419 description: List of multicast groups.420 type: object421 required: [ list ]422 additionalProperties: False423 properties:424 list:425 description: List of groups.426 type: array427 items:428 type: object429 required: [ name ]430 additionalProperties: False431 properties:432 name:433 description: |434 The name for the group, used to form the define and the value of the define.435 type: string436 # Start genetlink-c437 c-define-name:438 description: Override for the name of the define in C uAPI.439 type: string440 # End genetlink-c441 flags: *cmd_flags442 443 kernel-family:444 description: Additional global attributes used for kernel C code generation.445 type: object446 additionalProperties: False447 properties:448 headers:449 description: |450 List of extra headers which should be included in the source451 of the generated code.452 type: array453 items:454 type: string455 sock-priv:456 description: |457 Literal name of the type which is used within the kernel458 to store the socket state. The type / structure is internal459 to the kernel, and is not defined in the spec.460 type: string461