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