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        # End genetlink-legacy
128
129  attribute-sets:
130    description: Definition of attribute spaces for this family.
131    type: array
132    items:
133      description: Definition of a single attribute space.
134      type: object
135      required: [ name, attributes ]
136      additionalProperties: False
137      properties:
138        name:
139          description: |
140            Name used when referring to this space in other definitions, not used outside of the spec.
141          type: string
142        name-prefix:
143          description: |
144            Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
145          type: string
146        enum-name:
147          description: Name for the enum type of the attribute.
148          type: string
149        doc:
150          description: Documentation of the space.
151          type: string
152        subset-of:
153          description: |
154            Name of another space which this is a logical part of. Sub-spaces can be used to define
155            a limited group of attributes which are used in a nest.
156          type: string
157        # Start genetlink-c
158        attr-cnt-name:
159          description: The explicit name for constant holding the count of attributes (last attr + 1).
160          type: string
161        attr-max-name:
162          description: The explicit name for last member of attribute enum.
163          type: string
164        # End genetlink-c
165        attributes:
166          description: List of attributes in the space.
167          type: array
168          items:
169            type: object
170            required: [ name, type ]
171            additionalProperties: False
172            properties:
173              name:
174                type: string
175              type: &attr-type
176                enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64,
177                        string, nest, array-nest, nest-type-value ]
178              doc:
179                description: Documentation of the attribute.
180                type: string
181              value:
182                description: Value for the enum item representing this attribute in the uAPI.
183                $ref: '#/$defs/uint'
184              type-value:
185                description: Name of the value extracted from the type of a nest-type-value attribute.
186                type: array
187                items:
188                  type: string
189              byte-order:
190                enum: [ little-endian, big-endian ]
191              multi-attr:
192                type: boolean
193              nested-attributes:
194                description: Name of the space (sub-space) used inside the attribute.
195                type: string
196              enum:
197                description: Name of the enum type used for the attribute.
198                type: string
199              enum-as-flags:
200                description: |
201                  Treat the enum as flags. In most cases enum is either used as flags or as values.
202                  Sometimes, however, both forms are necessary, in which case header contains the enum
203                  form while specific attributes may request to convert the values into a bitfield.
204                type: boolean
205              checks:
206                description: Kernel input validation.
207                type: object
208                additionalProperties: False
209                properties:
210                  flags-mask:
211                    description: Name of the flags constant on which to base mask (unsigned scalar types only).
212                    type: string
213                  min:
214                    description: Min value for an integer attribute.
215                    type: integer
216                  min-len:
217                    description: Min length for a binary attribute.
218                    $ref: '#/$defs/len-or-define'
219                  max-len:
220                    description: Max length for a string or a binary attribute.
221                    $ref: '#/$defs/len-or-define'
222              sub-type: *attr-type
223              # Start genetlink-legacy
224              struct:
225                description: Name of the struct type used for the attribute.
226                type: string
227              # End genetlink-legacy
228
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  operations:
239    description: Operations supported by the protocol.
240    type: object
241    required: [ list ]
242    additionalProperties: False
243    properties:
244      enum-model:
245        description: |
246          The model of assigning values to the operations.
247          "unified" is the recommended model where all message types belong
248          to a single enum.
249          "directional" has the messages sent to the kernel and from the kernel
250          enumerated separately.
251        enum: [ unified, directional ] # Trim
252      name-prefix:
253        description: |
254          Prefix for the C enum name of the command. The name is formed by concatenating
255          the prefix with the upper case name of the command, with dashes replaced by underscores.
256        type: string
257      enum-name:
258        description: Name for the enum type with commands.
259        type: string
260      async-prefix:
261        description: Same as name-prefix but used to render notifications and events to separate enum.
262        type: string
263      async-enum:
264        description: Name for the enum type with notifications/events.
265        type: string
266      # Start genetlink-legacy
267      fixed-header: &fixed-header
268        description: |
269          Name of the structure defining the optional fixed-length protocol
270          header. This header is placed in a message after the netlink and
271          genetlink headers and before any attributes.
272        type: string
273      # End genetlink-legacy
274      list:
275        description: List of commands
276        type: array
277        items:
278          type: object
279          additionalProperties: False
280          required: [ name, doc ]
281          properties:
282            name:
283              description: Name of the operation, also defining its C enum value in uAPI.
284              type: string
285            doc:
286              description: Documentation for the command.
287              type: string
288            value:
289              description: Value for the enum in the uAPI.
290              $ref: '#/$defs/uint'
291            attribute-set:
292              description: |
293                Attribute space from which attributes directly in the requests and replies
294                to this command are defined.
295              type: string
296            flags: &cmd_flags
297              description: Command flags.
298              type: array
299              items:
300                enum: [ admin-perm ]
301            dont-validate:
302              description: Kernel attribute validation flags.
303              type: array
304              items:
305                enum: [ strict, dump ]
306            # Start genetlink-legacy
307            fixed-header: *fixed-header
308            # End genetlink-legacy
309            do: &subop-type
310              description: Main command handler.
311              type: object
312              additionalProperties: False
313              properties:
314                request: &subop-attr-list
315                  description: Definition of the request message for a given command.
316                  type: object
317                  additionalProperties: False
318                  properties:
319                    attributes:
320                      description: |
321                        Names of attributes from the attribute-set (not full attribute
322                        definitions, just names).
323                      type: array
324                      items:
325                        type: string
326                    # Start genetlink-legacy
327                    value:
328                      description: |
329                        ID of this message if value for request and response differ,
330                        i.e. requests and responses have different message enums.
331                      $ref: '#/$defs/uint'
332                    # End genetlink-legacy
333                reply: *subop-attr-list
334                pre:
335                  description: Hook for a function to run before the main callback (pre_doit or start).
336                  type: string
337                post:
338                  description: Hook for a function to run after the main callback (post_doit or done).
339                  type: string
340            dump: *subop-type
341            notify:
342              description: Name of the command sharing the reply type with this notification.
343              type: string
344            event:
345              type: object
346              additionalProperties: False
347              properties:
348                attributes:
349                  description: Explicit list of the attributes for the notification.
350                  type: array
351                  items:
352                    type: string
353            mcgrp:
354              description: Name of the multicast group generating given notification.
355              type: string
356  mcast-groups:
357    description: List of multicast groups.
358    type: object
359    required: [ list ]
360    additionalProperties: False
361    properties:
362      list:
363        description: List of groups.
364        type: array
365        items:
366          type: object
367          required: [ name ]
368          additionalProperties: False
369          properties:
370            name:
371              description: |
372                The name for the group, used to form the define and the value of the define.
373              type: string
374            # Start genetlink-c
375            c-define-name:
376              description: Override for the name of the define in C uAPI.
377              type: string
378            # End genetlink-c
379            flags: *cmd_flags
380