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