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