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