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              display-hint: &display-hint
172                description: |
173                  Optional format indicator that is intended only for choosing
174                  the right formatting mechanism when displaying values of this
175                  type.
176                enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
177
178      # Make sure name-prefix does not appear in subsets (subsets inherit naming)
179      dependencies:
180        name-prefix:
181          not:
182            required: [ subset-of ]
183        subset-of:
184          not:
185            required: [ name-prefix ]
186
187  operations:
188    description: Operations supported by the protocol.
189    type: object
190    required: [ list ]
191    additionalProperties: False
192    properties:
193      enum-model:
194        description: |
195          The model of assigning values to the operations.
196          "unified" is the recommended model where all message types belong
197          to a single enum.
198          "directional" has the messages sent to the kernel and from the kernel
199          enumerated separately.
200        enum: [ unified ]
201      name-prefix:
202        description: |
203          Prefix for the C enum name of the command. The name is formed by concatenating
204          the prefix with the upper case name of the command, with dashes replaced by underscores.
205        type: string
206      enum-name:
207        description: Name for the enum type with commands.
208        type: string
209      async-prefix:
210        description: Same as name-prefix but used to render notifications and events to separate enum.
211        type: string
212      async-enum:
213        description: Name for the enum type with notifications/events.
214        type: string
215      list:
216        description: List of commands
217        type: array
218        items:
219          type: object
220          additionalProperties: False
221          required: [ name, doc ]
222          properties:
223            name:
224              description: Name of the operation, also defining its C enum value in uAPI.
225              type: string
226            doc:
227              description: Documentation for the command.
228              type: string
229            value:
230              description: Value for the enum in the uAPI.
231              $ref: '#/$defs/uint'
232            attribute-set:
233              description: |
234                Attribute space from which attributes directly in the requests and replies
235                to this command are defined.
236              type: string
237            flags: &cmd_flags
238              description: Command flags.
239              type: array
240              items:
241                enum: [ admin-perm ]
242            dont-validate:
243              description: Kernel attribute validation flags.
244              type: array
245              items:
246                enum: [ strict, dump, dump-strict ]
247            do: &subop-type
248              description: Main command handler.
249              type: object
250              additionalProperties: False
251              properties:
252                request: &subop-attr-list
253                  description: Definition of the request message for a given command.
254                  type: object
255                  additionalProperties: False
256                  properties:
257                    attributes:
258                      description: |
259                        Names of attributes from the attribute-set (not full attribute
260                        definitions, just names).
261                      type: array
262                      items:
263                        type: string
264                reply: *subop-attr-list
265                pre:
266                  description: Hook for a function to run before the main callback (pre_doit or start).
267                  type: string
268                post:
269                  description: Hook for a function to run after the main callback (post_doit or done).
270                  type: string
271            dump: *subop-type
272            notify:
273              description: Name of the command sharing the reply type with this notification.
274              type: string
275            event:
276              type: object
277              additionalProperties: False
278              properties:
279                attributes:
280                  description: Explicit list of the attributes for the notification.
281                  type: array
282                  items:
283                    type: string
284            mcgrp:
285              description: Name of the multicast group generating given notification.
286              type: string
287  mcast-groups:
288    description: List of multicast groups.
289    type: object
290    required: [ list ]
291    additionalProperties: False
292    properties:
293      list:
294        description: List of groups.
295        type: array
296        items:
297          type: object
298          required: [ name ]
299          additionalProperties: False
300          properties:
301            name:
302              description: |
303                The name for the group, used to form the define and the value of the define.
304              type: string
305            flags: *cmd_flags
306