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