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