509 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/netlink-raw.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 17# Schema for specs18title: Protocol19description: Specification of a raw netlink protocol20type: object21required: [ name, doc, attribute-sets, operations ]22additionalProperties: False23properties:24 name:25 description: Name of the netlink family.26 type: string27 doc:28 type: string29 protocol:30 description: Schema compatibility level.31 enum: [ netlink-raw ] # Trim32 # Start netlink-raw33 protonum:34 description: Protocol number to use for netlink-raw35 type: integer36 # End netlink-raw37 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 # End genetlink-legacy64 65 definitions:66 description: List of type and constant definitions (enums, flags, defines).67 type: array68 items:69 type: object70 required: [ type, name ]71 additionalProperties: False72 properties:73 name:74 type: string75 header:76 description: For C-compatible languages, header which already defines this value.77 type: string78 type:79 enum: [ const, enum, flags, struct ] # Trim80 doc:81 type: string82 # For const83 value:84 description: For const - the value.85 type: [ string, integer ]86 # For enum and flags87 value-start:88 description: For enum or flags the literal initializer for the first value.89 type: [ string, integer ]90 entries:91 description: For enum or flags array of values.92 type: array93 items:94 oneOf:95 - type: string96 - type: object97 required: [ name ]98 additionalProperties: False99 properties:100 name:101 type: string102 value:103 type: integer104 doc:105 type: string106 render-max:107 description: Render the max members for this enum.108 type: boolean109 # Start genetlink-c110 enum-name:111 description: Name for enum, if empty no name will be used.112 type: [ string, "null" ]113 name-prefix:114 description: For enum the prefix of the values, optional.115 type: string116 # End genetlink-c117 # Start genetlink-legacy118 members:119 description: List of struct members. Only scalars and strings members allowed.120 type: array121 items:122 type: object123 required: [ name, type ]124 additionalProperties: False125 properties:126 name:127 type: string128 type:129 description: |130 The netlink attribute type. Members of type 'binary' or 'pad'131 must also have the 'len' property set.132 enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary, pad ]133 len:134 $ref: '#/$defs/len-or-define'135 byte-order:136 enum: [ little-endian, big-endian ]137 doc:138 description: Documentation for the struct member attribute.139 type: string140 enum:141 description: Name of the enum type used for the attribute.142 type: string143 enum-as-flags:144 description: |145 Treat the enum as flags. In most cases enum is either used as flags or as values.146 Sometimes, however, both forms are necessary, in which case header contains the enum147 form while specific attributes may request to convert the values into a bitfield.148 type: boolean149 display-hint: &display-hint150 description: |151 Optional format indicator that is intended only for choosing152 the right formatting mechanism when displaying values of this153 type.154 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]155 struct:156 description: Name of the nested struct type.157 type: string158 if:159 properties:160 type:161 const: pad162 then:163 required: [ len ]164 if:165 properties:166 type:167 const: binary168 then:169 oneOf:170 - required: [ len ]171 - required: [ struct ]172 # End genetlink-legacy173 174 attribute-sets:175 description: Definition of attribute spaces for this family.176 type: array177 items:178 description: Definition of a single attribute space.179 type: object180 required: [ name, attributes ]181 additionalProperties: False182 properties:183 name:184 description: |185 Name used when referring to this space in other definitions, not used outside of the spec.186 type: string187 name-prefix:188 description: |189 Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-190 type: string191 enum-name:192 description: |193 Name for the enum type of the attribute, if empty no name will be used.194 type: [ string, "null" ]195 doc:196 description: Documentation of the space.197 type: string198 subset-of:199 description: |200 Name of another space which this is a logical part of. Sub-spaces can be used to define201 a limited group of attributes which are used in a nest.202 type: string203 # Start genetlink-c204 attr-cnt-name:205 description: The explicit name for constant holding the count of attributes (last attr + 1).206 type: string207 attr-max-name:208 description: The explicit name for last member of attribute enum.209 type: string210 # End genetlink-c211 attributes:212 description: List of attributes in the space.213 type: array214 items:215 type: object216 required: [ name ]217 additionalProperties: False218 properties:219 name:220 type: string221 type: &attr-type222 description: The netlink attribute type223 enum: [ unused, pad, flag, binary, bitfield32,224 u8, u16, u32, u64, s8, s16, s32, s64,225 string, nest, indexed-array, nest-type-value,226 sub-message ]227 doc:228 description: Documentation of the attribute.229 type: string230 value:231 description: Value for the enum item representing this attribute in the uAPI.232 $ref: '#/$defs/uint'233 type-value:234 description: Name of the value extracted from the type of a nest-type-value attribute.235 type: array236 items:237 type: string238 byte-order:239 enum: [ little-endian, big-endian ]240 multi-attr:241 type: boolean242 nested-attributes:243 description: Name of the space (sub-space) used inside the attribute.244 type: string245 enum:246 description: Name of the enum type used for the attribute.247 type: string248 enum-as-flags:249 description: |250 Treat the enum as flags. In most cases enum is either used as flags or as values.251 Sometimes, however, both forms are necessary, in which case header contains the enum252 form while specific attributes may request to convert the values into a bitfield.253 type: boolean254 checks:255 description: Kernel input validation.256 type: object257 additionalProperties: False258 properties:259 flags-mask:260 description: Name of the flags constant on which to base mask (unsigned scalar types only).261 type: string262 min:263 description: Min value for an integer attribute.264 type: integer265 min-len:266 description: Min length for a binary attribute.267 $ref: '#/$defs/len-or-define'268 max-len:269 description: Max length for a string or a binary attribute.270 $ref: '#/$defs/len-or-define'271 exact-len:272 description: Exact length for a string or a binary attribute.273 $ref: '#/$defs/len-or-define'274 unterminated-ok:275 description: |276 For string attributes, do not check whether attribute277 contains the terminating null character.278 type: boolean279 sub-type: *attr-type280 display-hint: *display-hint281 # Start genetlink-c282 name-prefix:283 type: string284 # End genetlink-c285 # Start genetlink-legacy286 struct:287 description: Name of the struct type used for the attribute.288 type: string289 # End genetlink-legacy290 # Start netlink-raw291 sub-message:292 description: |293 Name of the sub-message definition to use for the attribute.294 type: string295 selector:296 description: |297 Name of the attribute to use for dynamic selection of sub-message298 format specifier.299 type: string300 # End netlink-raw301 302 # Make sure name-prefix does not appear in subsets (subsets inherit naming)303 dependencies:304 name-prefix:305 not:306 required: [ subset-of ]307 subset-of:308 not:309 required: [ name-prefix ]310 311 # type property is only required if not in subset definition312 if:313 properties:314 subset-of:315 not:316 type: string317 then:318 properties:319 attributes:320 items:321 required: [ type ]322 323 # Start netlink-raw324 sub-messages:325 description: Definition of sub message attributes326 type: array327 items:328 type: object329 additionalProperties: False330 required: [ name, formats ]331 properties:332 name:333 description: Name of the sub-message definition334 type: string335 formats:336 description: Dynamically selected format specifiers337 type: array338 items:339 type: object340 additionalProperties: False341 required: [ value ]342 properties:343 value:344 description: |345 Value to match for dynamic selection of sub-message format346 specifier.347 type: string348 fixed-header:349 description: |350 Name of the struct definition to use as the fixed header351 for the sub message.352 type: string353 attribute-set:354 description: |355 Name of the attribute space from which to resolve attributes356 in the sub message.357 type: string358 # End netlink-raw359 360 operations:361 description: Operations supported by the protocol.362 type: object363 required: [ list ]364 additionalProperties: False365 properties:366 enum-model:367 description: |368 The model of assigning values to the operations.369 "unified" is the recommended model where all message types belong370 to a single enum.371 "directional" has the messages sent to the kernel and from the kernel372 enumerated separately.373 enum: [ unified, directional ] # Trim374 name-prefix:375 description: |376 Prefix for the C enum name of the command. The name is formed by concatenating377 the prefix with the upper case name of the command, with dashes replaced by underscores.378 type: string379 enum-name:380 description: |381 Name for the enum type with commands, if empty no name will be used.382 type: [ string, "null" ]383 async-prefix:384 description: Same as name-prefix but used to render notifications and events to separate enum.385 type: string386 async-enum:387 description: |388 Name for the enum type with commands, if empty no name will be used.389 type: [ string, "null" ]390 # Start genetlink-legacy391 fixed-header: &fixed-header392 description: |393 Name of the structure defining the optional fixed-length protocol394 header. This header is placed in a message after the netlink and395 genetlink headers and before any attributes.396 type: string397 # End genetlink-legacy398 list:399 description: List of commands400 type: array401 items:402 type: object403 additionalProperties: False404 required: [ name, doc ]405 properties:406 name:407 description: Name of the operation, also defining its C enum value in uAPI.408 type: string409 doc:410 description: Documentation for the command.411 type: string412 value:413 description: Value for the enum in the uAPI.414 $ref: '#/$defs/uint'415 attribute-set:416 description: |417 Attribute space from which attributes directly in the requests and replies418 to this command are defined.419 type: string420 flags: &cmd_flags421 description: Command flags.422 type: array423 items:424 enum: [ admin-perm ]425 dont-validate:426 description: Kernel attribute validation flags.427 type: array428 items:429 enum: [ strict, dump ]430 # Start genetlink-legacy431 fixed-header: *fixed-header432 # End genetlink-legacy433 do: &subop-type434 description: Main command handler.435 type: object436 additionalProperties: False437 properties:438 request: &subop-attr-list439 description: Definition of the request message for a given command.440 type: object441 additionalProperties: False442 properties:443 attributes:444 description: |445 Names of attributes from the attribute-set (not full attribute446 definitions, just names).447 type: array448 items:449 type: string450 # Start genetlink-legacy451 value:452 description: |453 ID of this message if value for request and response differ,454 i.e. requests and responses have different message enums.455 $ref: '#/$defs/uint'456 # End genetlink-legacy457 reply: *subop-attr-list458 pre:459 description: Hook for a function to run before the main callback (pre_doit or start).460 type: string461 post:462 description: Hook for a function to run after the main callback (post_doit or done).463 type: string464 dump: *subop-type465 notify:466 description: Name of the command sharing the reply type with this notification.467 type: string468 event:469 type: object470 additionalProperties: False471 properties:472 attributes:473 description: Explicit list of the attributes for the notification.474 type: array475 items:476 type: string477 mcgrp:478 description: Name of the multicast group generating given notification.479 type: string480 mcast-groups:481 description: List of multicast groups.482 type: object483 required: [ list ]484 additionalProperties: False485 properties:486 list:487 description: List of groups.488 type: array489 items:490 type: object491 required: [ name ]492 additionalProperties: False493 properties:494 name:495 description: |496 The name for the group, used to form the define and the value of the define.497 type: string498 # Start genetlink-c499 c-define-name:500 description: Override for the name of the define in C uAPI.501 type: string502 # End genetlink-c503 flags: *cmd_flags504 # Start netlink-raw505 value:506 description: Value of the netlink multicast group in the uAPI.507 type: integer508 # End netlink-raw509