400 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-c.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 ]37 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 58 definitions:59 description: List of type and constant definitions (enums, flags, defines).60 type: array61 items:62 type: object63 required: [ type, name ]64 additionalProperties: False65 properties:66 name:67 type: string68 header:69 description: For C-compatible languages, header which already defines this value.70 type: string71 type:72 enum: [ const, enum, flags ]73 doc:74 type: string75 # For const76 value:77 description: For const - the value.78 type: [ string, integer ]79 # For enum and flags80 value-start:81 description: For enum or flags the literal initializer for the first value.82 type: [ string, integer ]83 entries:84 description: For enum or flags array of values.85 type: array86 items:87 oneOf:88 - type: string89 - type: object90 required: [ name ]91 additionalProperties: False92 properties:93 name:94 type: string95 value:96 type: integer97 doc:98 type: string99 render-max:100 description: Render the max members for this enum.101 type: boolean102 # Start genetlink-c103 enum-name:104 description: Name for enum, if empty no name will be used.105 type: [ string, "null" ]106 name-prefix:107 description: For enum the prefix of the values, optional.108 type: string109 # End genetlink-c110 111 attribute-sets:112 description: Definition of attribute spaces for this family.113 type: array114 items:115 description: Definition of a single attribute space.116 type: object117 required: [ name, attributes ]118 additionalProperties: False119 properties:120 name:121 description: |122 Name used when referring to this space in other definitions, not used outside of the spec.123 type: string124 name-prefix:125 description: |126 Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-127 type: string128 enum-name:129 description: |130 Name for the enum type of the attribute, if empty no name will be used.131 type: [ string, "null" ]132 doc:133 description: Documentation of the space.134 type: string135 subset-of:136 description: |137 Name of another space which this is a logical part of. Sub-spaces can be used to define138 a limited group of attributes which are used in a nest.139 type: string140 # Start genetlink-c141 attr-cnt-name:142 description: The explicit name for constant holding the count of attributes (last attr + 1).143 type: string144 attr-max-name:145 description: The explicit name for last member of attribute enum.146 type: string147 # End genetlink-c148 attributes:149 description: List of attributes in the space.150 type: array151 items:152 type: object153 required: [ name ]154 additionalProperties: False155 properties:156 name:157 type: string158 type: &attr-type159 enum: [ unused, pad, flag, binary,160 uint, sint, u8, u16, u32, u64, s32, s64,161 string, nest, indexed-array, nest-type-value ]162 doc:163 description: Documentation of the attribute.164 type: string165 value:166 description: Value for the enum item representing this attribute in the uAPI.167 $ref: '#/$defs/uint'168 type-value:169 description: Name of the value extracted from the type of a nest-type-value attribute.170 type: array171 items:172 type: string173 byte-order:174 enum: [ little-endian, big-endian ]175 multi-attr:176 type: boolean177 nested-attributes:178 description: Name of the space (sub-space) used inside the attribute.179 type: string180 enum:181 description: Name of the enum type used for the attribute.182 type: string183 enum-as-flags:184 description: |185 Treat the enum as flags. In most cases enum is either used as flags or as values.186 Sometimes, however, both forms are necessary, in which case header contains the enum187 form while specific attributes may request to convert the values into a bitfield.188 type: boolean189 checks:190 description: Kernel input validation.191 type: object192 additionalProperties: False193 properties:194 flags-mask:195 description: Name of the flags constant on which to base mask (unsigned scalar types only).196 type: string197 min:198 description: Min value for an integer attribute.199 $ref: '#/$defs/len-or-limit'200 max:201 description: Max value for an integer attribute.202 $ref: '#/$defs/len-or-limit'203 min-len:204 description: Min length for a binary attribute.205 $ref: '#/$defs/len-or-define'206 max-len:207 description: Max length for a string or a binary attribute.208 $ref: '#/$defs/len-or-define'209 exact-len:210 description: Exact length for a string or a binary attribute.211 $ref: '#/$defs/len-or-define'212 unterminated-ok:213 description: |214 For string attributes, do not check whether attribute215 contains the terminating null character.216 type: boolean217 sub-type: *attr-type218 display-hint: &display-hint219 description: |220 Optional format indicator that is intended only for choosing221 the right formatting mechanism when displaying values of this222 type.223 enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]224 # Start genetlink-c225 name-prefix:226 type: string227 # End genetlink-c228 229 # Make sure name-prefix does not appear in subsets (subsets inherit naming)230 dependencies:231 name-prefix:232 not:233 required: [ subset-of ]234 subset-of:235 not:236 required: [ name-prefix ]237 238 # type property is only required if not in subset definition239 if:240 properties:241 subset-of:242 not:243 type: string244 then:245 properties:246 attributes:247 items:248 required: [ type ]249 250 operations:251 description: Operations supported by the protocol.252 type: object253 required: [ list ]254 additionalProperties: False255 properties:256 enum-model:257 description: |258 The model of assigning values to the operations.259 "unified" is the recommended model where all message types belong260 to a single enum.261 "directional" has the messages sent to the kernel and from the kernel262 enumerated separately.263 enum: [ unified ]264 name-prefix:265 description: |266 Prefix for the C enum name of the command. The name is formed by concatenating267 the prefix with the upper case name of the command, with dashes replaced by underscores.268 type: string269 enum-name:270 description: |271 Name for the enum type with commands, if empty no name will be used.272 type: [ string, "null" ]273 async-prefix:274 description: Same as name-prefix but used to render notifications and events to separate enum.275 type: string276 async-enum:277 description: |278 Name for the enum type with commands, if empty no name will be used.279 type: [ string, "null" ]280 list:281 description: List of commands282 type: array283 items:284 type: object285 additionalProperties: False286 required: [ name, doc ]287 properties:288 name:289 description: Name of the operation, also defining its C enum value in uAPI.290 type: string291 doc:292 description: Documentation for the command.293 type: string294 value:295 description: Value for the enum in the uAPI.296 $ref: '#/$defs/uint'297 attribute-set:298 description: |299 Attribute space from which attributes directly in the requests and replies300 to this command are defined.301 type: string302 flags: &cmd_flags303 description: Command flags.304 type: array305 items:306 enum: [ admin-perm ]307 dont-validate:308 description: Kernel attribute validation flags.309 type: array310 items:311 enum: [ strict, dump, dump-strict ]312 config-cond:313 description: |314 Name of the kernel config option gating the presence of315 the operation, without the 'CONFIG_' prefix.316 type: string317 do: &subop-type318 description: Main command handler.319 type: object320 additionalProperties: False321 properties:322 request: &subop-attr-list323 description: Definition of the request message for a given command.324 type: object325 additionalProperties: False326 properties:327 attributes:328 description: |329 Names of attributes from the attribute-set (not full attribute330 definitions, just names).331 type: array332 items:333 type: string334 reply: *subop-attr-list335 pre:336 description: Hook for a function to run before the main callback (pre_doit or start).337 type: string338 post:339 description: Hook for a function to run after the main callback (post_doit or done).340 type: string341 dump: *subop-type342 notify:343 description: Name of the command sharing the reply type with this notification.344 type: string345 event:346 type: object347 additionalProperties: False348 properties:349 attributes:350 description: Explicit list of the attributes for the notification.351 type: array352 items:353 type: string354 mcgrp:355 description: Name of the multicast group generating given notification.356 type: string357 mcast-groups:358 description: List of multicast groups.359 type: object360 required: [ list ]361 additionalProperties: False362 properties:363 list:364 description: List of groups.365 type: array366 items:367 type: object368 required: [ name ]369 additionalProperties: False370 properties:371 name:372 description: |373 The name for the group, used to form the define and the value of the define.374 type: string375 # Start genetlink-c376 c-define-name:377 description: Override for the name of the define in C uAPI.378 type: string379 # End genetlink-c380 flags: *cmd_flags381 382 kernel-family:383 description: Additional global attributes used for kernel C code generation.384 type: object385 additionalProperties: False386 properties:387 headers:388 description: |389 List of extra headers which should be included in the source390 of the generated code.391 type: array392 items:393 type: string394 sock-priv:395 description: |396 Literal name of the type which is used within the kernel397 to store the socket state. The type / structure is internal398 to the kernel, and is not defined in the spec.399 type: string400