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
17# Schema for specs
18title: Protocol
19description: Specification of a genetlink protocol
20type: object
21required: [ name, doc, attribute-sets, operations ]
22additionalProperties: False
23properties:
24  name:
25    description: Name of the genetlink family.
26    type: string
27  doc:
28    type: string
29  version:
30    description: Generic Netlink family version. Default is 1.
31    type: integer
32    minimum: 1
33  protocol:
34    description: Schema compatibility level. Default is "genetlink".
35    enum: [ genetlink, genetlink-c, genetlink-legacy ] # Trim
36  uapi-header:
37    description: Path to the uAPI header, default is linux/${family-name}.h
38    type: string
39  # Start genetlink-c
40  c-family-name:
41    description: Name of the define for the family name.
42    type: string
43  c-version-name:
44    description: Name of the define for the verion of the family.
45    type: string
46  max-by-define:
47    description: Makes the number of attributes and commands be specified by a define, not an enum value.
48    type: boolean
49  # End genetlink-c
50  # Start genetlink-legacy
51  kernel-policy:
52    description: |
53      Defines if the input policy in the kernel is global, per-operation, or split per operation type.
54      Default is split.
55    enum: [ split, per-op, global ]
56  # End genetlink-legacy
57
58  definitions:
59    description: List of type and constant definitions (enums, flags, defines).
60    type: array
61    items:
62      type: object
63      required: [ type, name ]
64      additionalProperties: False
65      properties:
66        name:
67          type: string
68        header:
69          description: For C-compatible languages, header which already defines this value.
70          type: string
71        type:
72          enum: [ const, enum, flags, struct ] # Trim
73        doc:
74          type: string
75        # For const
76        value:
77          description: For const - the value.
78          type: [ string, integer ]
79        # For enum and flags
80        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: array
86          items:
87            oneOf:
88              - type: string
89              - type: object
90                required: [ name ]
91                additionalProperties: False
92                properties:
93                  name:
94                    type: string
95                  value:
96                    type: integer
97                  doc:
98                    type: string
99        render-max:
100          description: Render the max members for this enum.
101          type: boolean
102        # Start genetlink-c
103        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: string
109        # End genetlink-c
110        # Start genetlink-legacy
111        members:
112          description: List of struct members. Only scalars and strings members allowed.
113          type: array
114          items:
115            type: object
116            required: [ name, type ]
117            additionalProperties: False
118            properties:
119              name:
120                type: string
121              type:
122                enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string ]
123              len:
124                $ref: '#/$defs/len-or-define'
125              byte-order:
126                enum: [ little-endian, big-endian ]
127              doc:
128                description: Documentation for the struct member attribute.
129                type: string
130              enum:
131                description: Name of the enum type used for the attribute.
132                type: string
133        # End genetlink-legacy
134
135  attribute-sets:
136    description: Definition of attribute spaces for this family.
137    type: array
138    items:
139      description: Definition of a single attribute space.
140      type: object
141      required: [ name, attributes ]
142      additionalProperties: False
143      properties:
144        name:
145          description: |
146            Name used when referring to this space in other definitions, not used outside of the spec.
147          type: string
148        name-prefix:
149          description: |
150            Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
151          type: string
152        enum-name:
153          description: Name for the enum type of the attribute.
154          type: string
155        doc:
156          description: Documentation of the space.
157          type: string
158        subset-of:
159          description: |
160            Name of another space which this is a logical part of. Sub-spaces can be used to define
161            a limited group of attributes which are used in a nest.
162          type: string
163        # Start genetlink-c
164        attr-cnt-name:
165          description: The explicit name for constant holding the count of attributes (last attr + 1).
166          type: string
167        attr-max-name:
168          description: The explicit name for last member of attribute enum.
169          type: string
170        # End genetlink-c
171        attributes:
172          description: List of attributes in the space.
173          type: array
174          items:
175            type: object
176            required: [ name, type ]
177            additionalProperties: False
178            properties:
179              name:
180                type: string
181              type: &attr-type
182                enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64,
183                        string, nest, array-nest, nest-type-value ]
184              doc:
185                description: Documentation of the attribute.
186                type: string
187              value:
188                description: Value for the enum item representing this attribute in the uAPI.
189                $ref: '#/$defs/uint'
190              type-value:
191                description: Name of the value extracted from the type of a nest-type-value attribute.
192                type: array
193                items:
194                  type: string
195              byte-order:
196                enum: [ little-endian, big-endian ]
197              multi-attr:
198                type: boolean
199              nested-attributes:
200                description: Name of the space (sub-space) used inside the attribute.
201                type: string
202              enum:
203                description: Name of the enum type used for the attribute.
204                type: string
205              enum-as-flags:
206                description: |
207                  Treat the enum as flags. In most cases enum is either used as flags or as values.
208                  Sometimes, however, both forms are necessary, in which case header contains the enum
209                  form while specific attributes may request to convert the values into a bitfield.
210                type: boolean
211              checks:
212                description: Kernel input validation.
213                type: object
214                additionalProperties: False
215                properties:
216                  flags-mask:
217                    description: Name of the flags constant on which to base mask (unsigned scalar types only).
218                    type: string
219                  min:
220                    description: Min value for an integer attribute.
221                    type: integer
222                  min-len:
223                    description: Min length for a binary attribute.
224                    $ref: '#/$defs/len-or-define'
225                  max-len:
226                    description: Max length for a string or a binary attribute.
227                    $ref: '#/$defs/len-or-define'
228              sub-type: *attr-type
229              # Start genetlink-c
230              name-prefix:
231                type: string
232              # End genetlink-c
233              # Start genetlink-legacy
234              struct:
235                description: Name of the struct type used for the attribute.
236                type: string
237              # End genetlink-legacy
238
239      # Make sure name-prefix does not appear in subsets (subsets inherit naming)
240      dependencies:
241        name-prefix:
242          not:
243            required: [ subset-of ]
244        subset-of:
245          not:
246            required: [ name-prefix ]
247
248  operations:
249    description: Operations supported by the protocol.
250    type: object
251    required: [ list ]
252    additionalProperties: False
253    properties:
254      enum-model:
255        description: |
256          The model of assigning values to the operations.
257          "unified" is the recommended model where all message types belong
258          to a single enum.
259          "directional" has the messages sent to the kernel and from the kernel
260          enumerated separately.
261        enum: [ unified, directional ] # Trim
262      name-prefix:
263        description: |
264          Prefix for the C enum name of the command. The name is formed by concatenating
265          the prefix with the upper case name of the command, with dashes replaced by underscores.
266        type: string
267      enum-name:
268        description: Name for the enum type with commands.
269        type: string
270      async-prefix:
271        description: Same as name-prefix but used to render notifications and events to separate enum.
272        type: string
273      async-enum:
274        description: Name for the enum type with notifications/events.
275        type: string
276      # Start genetlink-legacy
277      fixed-header: &fixed-header
278        description: |
279          Name of the structure defining the optional fixed-length protocol
280          header. This header is placed in a message after the netlink and
281          genetlink headers and before any attributes.
282        type: string
283      # End genetlink-legacy
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 ]
316            # Start genetlink-legacy
317            fixed-header: *fixed-header
318            # End genetlink-legacy
319            do: &subop-type
320              description: Main command handler.
321              type: object
322              additionalProperties: False
323              properties:
324                request: &subop-attr-list
325                  description: Definition of the request message for a given command.
326                  type: object
327                  additionalProperties: False
328                  properties:
329                    attributes:
330                      description: |
331                        Names of attributes from the attribute-set (not full attribute
332                        definitions, just names).
333                      type: array
334                      items:
335                        type: string
336                    # Start genetlink-legacy
337                    value:
338                      description: |
339                        ID of this message if value for request and response differ,
340                        i.e. requests and responses have different message enums.
341                      $ref: '#/$defs/uint'
342                    # End genetlink-legacy
343                reply: *subop-attr-list
344                pre:
345                  description: Hook for a function to run before the main callback (pre_doit or start).
346                  type: string
347                post:
348                  description: Hook for a function to run after the main callback (post_doit or done).
349                  type: string
350            dump: *subop-type
351            notify:
352              description: Name of the command sharing the reply type with this notification.
353              type: string
354            event:
355              type: object
356              additionalProperties: False
357              properties:
358                attributes:
359                  description: Explicit list of the attributes for the notification.
360                  type: array
361                  items:
362                    type: string
363            mcgrp:
364              description: Name of the multicast group generating given notification.
365              type: string
366  mcast-groups:
367    description: List of multicast groups.
368    type: object
369    required: [ list ]
370    additionalProperties: False
371    properties:
372      list:
373        description: List of groups.
374        type: array
375        items:
376          type: object
377          required: [ name ]
378          additionalProperties: False
379          properties:
380            name:
381              description: |
382                The name for the group, used to form the define and the value of the define.
383              type: string
384            # Start genetlink-c
385            c-define-name:
386              description: Override for the name of the define in C uAPI.
387              type: string
388            # End genetlink-c
389            flags: *cmd_flags
390