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