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