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