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  cmd-max-name:
51    description: Name of the define for the last operation in the list.
52    type: string
53  cmd-cnt-name:
54    description: The explicit name for constant holding the count of operations (last operation + 1).
55    type: string
56  # End genetlink-c
57  # Start genetlink-legacy
58  kernel-policy:
59    description: |
60      Defines if the input policy in the kernel is global, per-operation, or split per operation type.
61      Default is split.
62    enum: [ split, per-op, global ]
63  # End genetlink-legacy
64
65  definitions:
66    description: List of type and constant definitions (enums, flags, defines).
67    type: array
68    items:
69      type: object
70      required: [ type, name ]
71      additionalProperties: False
72      properties:
73        name:
74          type: string
75        header:
76          description: For C-compatible languages, header which already defines this value.
77          type: string
78        type:
79          enum: [ const, enum, flags, struct ] # Trim
80        doc:
81          type: string
82        # For const
83        value:
84          description: For const - the value.
85          type: [ string, integer ]
86        # For enum and flags
87        value-start:
88          description: For enum or flags the literal initializer for the first value.
89          type: [ string, integer ]
90        entries:
91          description: For enum or flags array of values.
92          type: array
93          items:
94            oneOf:
95              - type: string
96              - type: object
97                required: [ name ]
98                additionalProperties: False
99                properties:
100                  name:
101                    type: string
102                  value:
103                    type: integer
104                  doc:
105                    type: string
106        render-max:
107          description: Render the max members for this enum.
108          type: boolean
109        # Start genetlink-c
110        enum-name:
111          description: Name for enum, if empty no name will be used.
112          type: [ string, "null" ]
113        name-prefix:
114          description: For enum the prefix of the values, optional.
115          type: string
116        # End genetlink-c
117        # Start genetlink-legacy
118        members:
119          description: List of struct members. Only scalars and strings members allowed.
120          type: array
121          items:
122            type: object
123            required: [ name, type ]
124            additionalProperties: False
125            properties:
126              name:
127                type: string
128              type:
129                description: |
130                  The netlink attribute type. Members of type 'binary' or 'pad'
131                  must also have the 'len' property set.
132                enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary, pad ]
133              len:
134                $ref: '#/$defs/len-or-define'
135              byte-order:
136                enum: [ little-endian, big-endian ]
137              doc:
138                description: Documentation for the struct member attribute.
139                type: string
140              enum:
141                description: Name of the enum type used for the attribute.
142                type: string
143              enum-as-flags:
144                description: |
145                  Treat the enum as flags. In most cases enum is either used as flags or as values.
146                  Sometimes, however, both forms are necessary, in which case header contains the enum
147                  form while specific attributes may request to convert the values into a bitfield.
148                type: boolean
149              display-hint: &display-hint
150                description: |
151                  Optional format indicator that is intended only for choosing
152                  the right formatting mechanism when displaying values of this
153                  type.
154                enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
155              struct:
156                description: Name of the nested struct type.
157                type: string
158            if:
159              properties:
160                type:
161                  const: pad
162            then:
163              required: [ len ]
164            if:
165              properties:
166                type:
167                  const: binary
168            then:
169              oneOf:
170                - required: [ len ]
171                - required: [ struct ]
172        # End genetlink-legacy
173
174  attribute-sets:
175    description: Definition of attribute spaces for this family.
176    type: array
177    items:
178      description: Definition of a single attribute space.
179      type: object
180      required: [ name, attributes ]
181      additionalProperties: False
182      properties:
183        name:
184          description: |
185            Name used when referring to this space in other definitions, not used outside of the spec.
186          type: string
187        name-prefix:
188          description: |
189            Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
190          type: string
191        enum-name:
192          description: |
193            Name for the enum type of the attribute, if empty no name will be used.
194          type: [ string, "null" ]
195        doc:
196          description: Documentation of the space.
197          type: string
198        subset-of:
199          description: |
200            Name of another space which this is a logical part of. Sub-spaces can be used to define
201            a limited group of attributes which are used in a nest.
202          type: string
203        # Start genetlink-c
204        attr-cnt-name:
205          description: The explicit name for constant holding the count of attributes (last attr + 1).
206          type: string
207        attr-max-name:
208          description: The explicit name for last member of attribute enum.
209          type: string
210        header:
211          description: For C-compatible languages, header which already defines this attribute set.
212          type: string
213        # End genetlink-c
214        attributes:
215          description: List of attributes in the space.
216          type: array
217          items:
218            type: object
219            required: [ name ]
220            additionalProperties: False
221            properties:
222              name:
223                type: string
224              type: &attr-type
225                description: The netlink attribute type
226                enum: [ unused, pad, flag, binary, bitfield32,
227                        uint, sint, u8, u16, u32, u64, s8, s16, s32, s64,
228                        string, nest, indexed-array, nest-type-value,
229                        sub-message ]
230              doc:
231                description: Documentation of the attribute.
232                type: string
233              value:
234                description: Value for the enum item representing this attribute in the uAPI.
235                $ref: '#/$defs/uint'
236              type-value:
237                description: Name of the value extracted from the type of a nest-type-value attribute.
238                type: array
239                items:
240                  type: string
241              byte-order:
242                enum: [ little-endian, big-endian ]
243              multi-attr:
244                type: boolean
245              nested-attributes:
246                description: Name of the space (sub-space) used inside the attribute.
247                type: string
248              enum:
249                description: Name of the enum type used for the attribute.
250                type: string
251              enum-as-flags:
252                description: |
253                  Treat the enum as flags. In most cases enum is either used as flags or as values.
254                  Sometimes, however, both forms are necessary, in which case header contains the enum
255                  form while specific attributes may request to convert the values into a bitfield.
256                type: boolean
257              checks:
258                description: Kernel input validation.
259                type: object
260                additionalProperties: False
261                properties:
262                  flags-mask:
263                    description: Name of the flags constant on which to base mask (unsigned scalar types only).
264                    type: string
265                  min:
266                    description: Min value for an integer attribute.
267                    type: integer
268                  min-len:
269                    description: Min length for a binary attribute.
270                    $ref: '#/$defs/len-or-define'
271                  max-len:
272                    description: Max length for a string or a binary attribute.
273                    $ref: '#/$defs/len-or-define'
274                  exact-len:
275                    description: Exact length for a string or a binary attribute.
276                    $ref: '#/$defs/len-or-define'
277                  unterminated-ok:
278                    description: |
279                      For string attributes, do not check whether attribute
280                      contains the terminating null character.
281                    type: boolean
282              sub-type: *attr-type
283              display-hint: *display-hint
284              # Start genetlink-c
285              name-prefix:
286                type: string
287              # End genetlink-c
288              # Start genetlink-legacy
289              struct:
290                description: Name of the struct type used for the attribute.
291                type: string
292              # End genetlink-legacy
293              # Start netlink-raw
294              sub-message:
295                description: |
296                  Name of the sub-message definition to use for the attribute.
297                type: string
298              selector:
299                description: |
300                  Name of the attribute to use for dynamic selection of sub-message
301                  format specifier.
302                type: string
303              # End netlink-raw
304
305      # Make sure name-prefix does not appear in subsets (subsets inherit naming)
306      dependencies:
307        name-prefix:
308          not:
309            required: [ subset-of ]
310        subset-of:
311          not:
312            required: [ name-prefix ]
313
314      # type property is only required if not in subset definition
315      if:
316        properties:
317          subset-of:
318            not:
319              type: string
320      then:
321        properties:
322          attributes:
323            items:
324              required: [ type ]
325
326  # Start netlink-raw
327  sub-messages:
328    description: Definition of sub message attributes
329    type: array
330    items:
331      type: object
332      additionalProperties: False
333      required: [ name, formats ]
334      properties:
335        name:
336          description: Name of the sub-message definition
337          type: string
338        formats:
339          description: Dynamically selected format specifiers
340          type: array
341          items:
342            type: object
343            additionalProperties: False
344            required: [ value ]
345            properties:
346              value:
347                description: |
348                  Value to match for dynamic selection of sub-message format
349                  specifier.
350                type: string
351              fixed-header:
352                description: |
353                  Name of the struct definition to use as the fixed header
354                  for the sub message.
355                type: string
356              attribute-set:
357                description: |
358                  Name of the attribute space from which to resolve attributes
359                  in the sub message.
360                type: string
361  # End netlink-raw
362
363  operations:
364    description: Operations supported by the protocol.
365    type: object
366    required: [ list ]
367    additionalProperties: False
368    properties:
369      enum-model:
370        description: |
371          The model of assigning values to the operations.
372          "unified" is the recommended model where all message types belong
373          to a single enum.
374          "directional" has the messages sent to the kernel and from the kernel
375          enumerated separately.
376        enum: [ unified, directional ] # Trim
377      name-prefix:
378        description: |
379          Prefix for the C enum name of the command. The name is formed by concatenating
380          the prefix with the upper case name of the command, with dashes replaced by underscores.
381        type: string
382      enum-name:
383        description: |
384          Name for the enum type with commands, if empty no name will be used.
385        type: [ string, "null" ]
386      async-prefix:
387        description: Same as name-prefix but used to render notifications and events to separate enum.
388        type: string
389      async-enum:
390        description: |
391          Name for the enum type with commands, if empty no name will be used.
392        type: [ string, "null" ]
393      # Start genetlink-legacy
394      fixed-header: &fixed-header
395        description: |
396          Name of the structure defining the optional fixed-length protocol
397          header. This header is placed in a message after the netlink and
398          genetlink headers and before any attributes.
399        type: string
400      # End genetlink-legacy
401      list:
402        description: List of commands
403        type: array
404        items:
405          type: object
406          additionalProperties: False
407          required: [ name, doc ]
408          properties:
409            name:
410              description: Name of the operation, also defining its C enum value in uAPI.
411              type: string
412            doc:
413              description: Documentation for the command.
414              type: string
415            value:
416              description: Value for the enum in the uAPI.
417              $ref: '#/$defs/uint'
418            attribute-set:
419              description: |
420                Attribute space from which attributes directly in the requests and replies
421                to this command are defined.
422              type: string
423            flags: &cmd_flags
424              description: Command flags.
425              type: array
426              items:
427                enum: [ admin-perm ]
428            dont-validate:
429              description: Kernel attribute validation flags.
430              type: array
431              items:
432                enum: [ strict, dump ]
433            # Start genetlink-legacy
434            fixed-header: *fixed-header
435            # End genetlink-legacy
436            do: &subop-type
437              description: Main command handler.
438              type: object
439              additionalProperties: False
440              properties:
441                request: &subop-attr-list
442                  description: Definition of the request message for a given command.
443                  type: object
444                  additionalProperties: False
445                  properties:
446                    attributes:
447                      description: |
448                        Names of attributes from the attribute-set (not full attribute
449                        definitions, just names).
450                      type: array
451                      items:
452                        type: string
453                    # Start genetlink-legacy
454                    value:
455                      description: |
456                        ID of this message if value for request and response differ,
457                        i.e. requests and responses have different message enums.
458                      $ref: '#/$defs/uint'
459                    # End genetlink-legacy
460                reply: *subop-attr-list
461                pre:
462                  description: Hook for a function to run before the main callback (pre_doit or start).
463                  type: string
464                post:
465                  description: Hook for a function to run after the main callback (post_doit or done).
466                  type: string
467            dump: *subop-type
468            notify:
469              description: Name of the command sharing the reply type with this notification.
470              type: string
471            event:
472              type: object
473              additionalProperties: False
474              properties:
475                attributes:
476                  description: Explicit list of the attributes for the notification.
477                  type: array
478                  items:
479                    type: string
480            mcgrp:
481              description: Name of the multicast group generating given notification.
482              type: string
483  mcast-groups:
484    description: List of multicast groups.
485    type: object
486    required: [ list ]
487    additionalProperties: False
488    properties:
489      list:
490        description: List of groups.
491        type: array
492        items:
493          type: object
494          required: [ name ]
495          additionalProperties: False
496          properties:
497            name:
498              description: |
499                The name for the group, used to form the define and the value of the define.
500              type: string
501            # Start genetlink-c
502            c-define-name:
503              description: Override for the name of the define in C uAPI.
504              type: string
505            # End genetlink-c
506            flags: *cmd_flags
507            # Start netlink-raw
508            value:
509              description: Value of the netlink multicast group in the uAPI.
510              type: integer
511            # End netlink-raw
512