mirror of
https://github.com/torvalds/linux.git
synced 2024-11-29 07:31:29 +00:00
de2d98743b
Add a 'sub-message' attribute type with a selector that supports
polymorphic attribute formats for raw netlink families like tc.
A sub-message attribute uses the value of another attribute as a
selector key to choose the right sub-message format. For example if the
following attribute has already been decoded:
{ "kind": "gre" }
and we encounter the following attribute spec:
-
name: data
type: sub-message
sub-message: linkinfo-data-msg
selector: kind
Then we look for a sub-message definition called 'linkinfo-data-msg' and
use the value of the 'kind' attribute i.e. 'gre' as the key to choose
the correct format for the sub-message:
sub-messages:
name: linkinfo-data-msg
formats:
-
value: bridge
attribute-set: linkinfo-bridge-attrs
-
value: gre
attribute-set: linkinfo-gre-attrs
-
value: geneve
attribute-set: linkinfo-geneve-attrs
This would decode the attribute value as a sub-message with the
attribute-set called 'linkinfo-gre-attrs' as the attribute space.
A sub-message can have an optional 'fixed-header' followed by zero or
more attributes from an attribute-set. For example the following
'tc-options-msg' sub-message defines message formats that use a mixture
of fixed-header, attribute-set or both together:
sub-messages:
-
name: tc-options-msg
formats:
-
value: bfifo
fixed-header: tc-fifo-qopt
-
value: cake
attribute-set: tc-cake-attrs
-
value: netem
fixed-header: tc-netem-qopt
attribute-set: tc-netem-attrs
Reviewed-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Link: https://lore.kernel.org/r/20231215093720.18774-3-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
492 lines
17 KiB
YAML
492 lines
17 KiB
YAML
# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
|
|
%YAML 1.2
|
|
---
|
|
$id: http://kernel.org/schemas/netlink/netlink-raw.yaml#
|
|
$schema: https://json-schema.org/draft-07/schema
|
|
|
|
# Common defines
|
|
$defs:
|
|
uint:
|
|
type: integer
|
|
minimum: 0
|
|
len-or-define:
|
|
type: [ string, integer ]
|
|
pattern: ^[0-9A-Za-z_]+( - 1)?$
|
|
minimum: 0
|
|
|
|
# Schema for specs
|
|
title: Protocol
|
|
description: Specification of a raw netlink protocol
|
|
type: object
|
|
required: [ name, doc, attribute-sets, operations ]
|
|
additionalProperties: False
|
|
properties:
|
|
name:
|
|
description: Name of the netlink family.
|
|
type: string
|
|
doc:
|
|
type: string
|
|
protocol:
|
|
description: Schema compatibility level.
|
|
enum: [ netlink-raw ] # Trim
|
|
# Start netlink-raw
|
|
protonum:
|
|
description: Protocol number to use for netlink-raw
|
|
type: integer
|
|
# End netlink-raw
|
|
uapi-header:
|
|
description: Path to the uAPI header, default is linux/${family-name}.h
|
|
type: string
|
|
# Start genetlink-c
|
|
c-family-name:
|
|
description: Name of the define for the family name.
|
|
type: string
|
|
c-version-name:
|
|
description: Name of the define for the version of the family.
|
|
type: string
|
|
max-by-define:
|
|
description: Makes the number of attributes and commands be specified by a define, not an enum value.
|
|
type: boolean
|
|
cmd-max-name:
|
|
description: Name of the define for the last operation in the list.
|
|
type: string
|
|
cmd-cnt-name:
|
|
description: The explicit name for constant holding the count of operations (last operation + 1).
|
|
type: string
|
|
# End genetlink-c
|
|
# Start genetlink-legacy
|
|
kernel-policy:
|
|
description: |
|
|
Defines if the input policy in the kernel is global, per-operation, or split per operation type.
|
|
Default is split.
|
|
enum: [ split, per-op, global ]
|
|
# End genetlink-legacy
|
|
|
|
definitions:
|
|
description: List of type and constant definitions (enums, flags, defines).
|
|
type: array
|
|
items:
|
|
type: object
|
|
required: [ type, name ]
|
|
additionalProperties: False
|
|
properties:
|
|
name:
|
|
type: string
|
|
header:
|
|
description: For C-compatible languages, header which already defines this value.
|
|
type: string
|
|
type:
|
|
enum: [ const, enum, flags, struct ] # Trim
|
|
doc:
|
|
type: string
|
|
# For const
|
|
value:
|
|
description: For const - the value.
|
|
type: [ string, integer ]
|
|
# For enum and flags
|
|
value-start:
|
|
description: For enum or flags the literal initializer for the first value.
|
|
type: [ string, integer ]
|
|
entries:
|
|
description: For enum or flags array of values.
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: string
|
|
- type: object
|
|
required: [ name ]
|
|
additionalProperties: False
|
|
properties:
|
|
name:
|
|
type: string
|
|
value:
|
|
type: integer
|
|
doc:
|
|
type: string
|
|
render-max:
|
|
description: Render the max members for this enum.
|
|
type: boolean
|
|
# Start genetlink-c
|
|
enum-name:
|
|
description: Name for enum, if empty no name will be used.
|
|
type: [ string, "null" ]
|
|
name-prefix:
|
|
description: For enum the prefix of the values, optional.
|
|
type: string
|
|
# End genetlink-c
|
|
# Start genetlink-legacy
|
|
members:
|
|
description: List of struct members. Only scalars and strings members allowed.
|
|
type: array
|
|
items:
|
|
type: object
|
|
required: [ name, type ]
|
|
additionalProperties: False
|
|
properties:
|
|
name:
|
|
type: string
|
|
type:
|
|
description: |
|
|
The netlink attribute type. Members of type 'binary' or 'pad'
|
|
must also have the 'len' property set.
|
|
enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary, pad ]
|
|
len:
|
|
$ref: '#/$defs/len-or-define'
|
|
byte-order:
|
|
enum: [ little-endian, big-endian ]
|
|
doc:
|
|
description: Documentation for the struct member attribute.
|
|
type: string
|
|
enum:
|
|
description: Name of the enum type used for the attribute.
|
|
type: string
|
|
enum-as-flags:
|
|
description: |
|
|
Treat the enum as flags. In most cases enum is either used as flags or as values.
|
|
Sometimes, however, both forms are necessary, in which case header contains the enum
|
|
form while specific attributes may request to convert the values into a bitfield.
|
|
type: boolean
|
|
display-hint: &display-hint
|
|
description: |
|
|
Optional format indicator that is intended only for choosing
|
|
the right formatting mechanism when displaying values of this
|
|
type.
|
|
enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
|
|
if:
|
|
properties:
|
|
type:
|
|
oneOf:
|
|
- const: binary
|
|
- const: pad
|
|
then:
|
|
required: [ len ]
|
|
# End genetlink-legacy
|
|
|
|
attribute-sets:
|
|
description: Definition of attribute spaces for this family.
|
|
type: array
|
|
items:
|
|
description: Definition of a single attribute space.
|
|
type: object
|
|
required: [ name, attributes ]
|
|
additionalProperties: False
|
|
properties:
|
|
name:
|
|
description: |
|
|
Name used when referring to this space in other definitions, not used outside of the spec.
|
|
type: string
|
|
name-prefix:
|
|
description: |
|
|
Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
|
|
type: string
|
|
enum-name:
|
|
description: Name for the enum type of the attribute.
|
|
type: string
|
|
doc:
|
|
description: Documentation of the space.
|
|
type: string
|
|
subset-of:
|
|
description: |
|
|
Name of another space which this is a logical part of. Sub-spaces can be used to define
|
|
a limited group of attributes which are used in a nest.
|
|
type: string
|
|
# Start genetlink-c
|
|
attr-cnt-name:
|
|
description: The explicit name for constant holding the count of attributes (last attr + 1).
|
|
type: string
|
|
attr-max-name:
|
|
description: The explicit name for last member of attribute enum.
|
|
type: string
|
|
# End genetlink-c
|
|
attributes:
|
|
description: List of attributes in the space.
|
|
type: array
|
|
items:
|
|
type: object
|
|
required: [ name ]
|
|
additionalProperties: False
|
|
properties:
|
|
name:
|
|
type: string
|
|
type: &attr-type
|
|
description: The netlink attribute type
|
|
enum: [ unused, pad, flag, binary, bitfield32,
|
|
u8, u16, u32, u64, s8, s16, s32, s64,
|
|
string, nest, array-nest, nest-type-value,
|
|
sub-message ]
|
|
doc:
|
|
description: Documentation of the attribute.
|
|
type: string
|
|
value:
|
|
description: Value for the enum item representing this attribute in the uAPI.
|
|
$ref: '#/$defs/uint'
|
|
type-value:
|
|
description: Name of the value extracted from the type of a nest-type-value attribute.
|
|
type: array
|
|
items:
|
|
type: string
|
|
byte-order:
|
|
enum: [ little-endian, big-endian ]
|
|
multi-attr:
|
|
type: boolean
|
|
nested-attributes:
|
|
description: Name of the space (sub-space) used inside the attribute.
|
|
type: string
|
|
enum:
|
|
description: Name of the enum type used for the attribute.
|
|
type: string
|
|
enum-as-flags:
|
|
description: |
|
|
Treat the enum as flags. In most cases enum is either used as flags or as values.
|
|
Sometimes, however, both forms are necessary, in which case header contains the enum
|
|
form while specific attributes may request to convert the values into a bitfield.
|
|
type: boolean
|
|
checks:
|
|
description: Kernel input validation.
|
|
type: object
|
|
additionalProperties: False
|
|
properties:
|
|
flags-mask:
|
|
description: Name of the flags constant on which to base mask (unsigned scalar types only).
|
|
type: string
|
|
min:
|
|
description: Min value for an integer attribute.
|
|
type: integer
|
|
min-len:
|
|
description: Min length for a binary attribute.
|
|
$ref: '#/$defs/len-or-define'
|
|
max-len:
|
|
description: Max length for a string or a binary attribute.
|
|
$ref: '#/$defs/len-or-define'
|
|
exact-len:
|
|
description: Exact length for a string or a binary attribute.
|
|
$ref: '#/$defs/len-or-define'
|
|
sub-type: *attr-type
|
|
display-hint: *display-hint
|
|
# Start genetlink-c
|
|
name-prefix:
|
|
type: string
|
|
# End genetlink-c
|
|
# Start genetlink-legacy
|
|
struct:
|
|
description: Name of the struct type used for the attribute.
|
|
type: string
|
|
# End genetlink-legacy
|
|
# Start netlink-raw
|
|
sub-message:
|
|
description: |
|
|
Name of the sub-message definition to use for the attribute.
|
|
type: string
|
|
selector:
|
|
description: |
|
|
Name of the attribute to use for dynamic selection of sub-message
|
|
format specifier.
|
|
type: string
|
|
# End netlink-raw
|
|
|
|
# Make sure name-prefix does not appear in subsets (subsets inherit naming)
|
|
dependencies:
|
|
name-prefix:
|
|
not:
|
|
required: [ subset-of ]
|
|
subset-of:
|
|
not:
|
|
required: [ name-prefix ]
|
|
|
|
# type property is only required if not in subset definition
|
|
if:
|
|
properties:
|
|
subset-of:
|
|
not:
|
|
type: string
|
|
then:
|
|
properties:
|
|
attributes:
|
|
items:
|
|
required: [ type ]
|
|
|
|
# Start netlink-raw
|
|
sub-messages:
|
|
description: Definition of sub message attributes
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: False
|
|
required: [ name, formats ]
|
|
properties:
|
|
name:
|
|
description: Name of the sub-message definition
|
|
type: string
|
|
formats:
|
|
description: Dynamically selected format specifiers
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: False
|
|
required: [ value ]
|
|
properties:
|
|
value:
|
|
description: |
|
|
Value to match for dynamic selection of sub-message format
|
|
specifier.
|
|
type: string
|
|
fixed-header:
|
|
description: |
|
|
Name of the struct definition to use as the fixed header
|
|
for the sub message.
|
|
type: string
|
|
attribute-set:
|
|
description: |
|
|
Name of the attribute space from which to resolve attributes
|
|
in the sub message.
|
|
type: string
|
|
# End netlink-raw
|
|
|
|
operations:
|
|
description: Operations supported by the protocol.
|
|
type: object
|
|
required: [ list ]
|
|
additionalProperties: False
|
|
properties:
|
|
enum-model:
|
|
description: |
|
|
The model of assigning values to the operations.
|
|
"unified" is the recommended model where all message types belong
|
|
to a single enum.
|
|
"directional" has the messages sent to the kernel and from the kernel
|
|
enumerated separately.
|
|
enum: [ unified, directional ] # Trim
|
|
name-prefix:
|
|
description: |
|
|
Prefix for the C enum name of the command. The name is formed by concatenating
|
|
the prefix with the upper case name of the command, with dashes replaced by underscores.
|
|
type: string
|
|
enum-name:
|
|
description: Name for the enum type with commands.
|
|
type: string
|
|
async-prefix:
|
|
description: Same as name-prefix but used to render notifications and events to separate enum.
|
|
type: string
|
|
async-enum:
|
|
description: Name for the enum type with notifications/events.
|
|
type: string
|
|
# Start genetlink-legacy
|
|
fixed-header: &fixed-header
|
|
description: |
|
|
Name of the structure defining the optional fixed-length protocol
|
|
header. This header is placed in a message after the netlink and
|
|
genetlink headers and before any attributes.
|
|
type: string
|
|
# End genetlink-legacy
|
|
list:
|
|
description: List of commands
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: False
|
|
required: [ name, doc ]
|
|
properties:
|
|
name:
|
|
description: Name of the operation, also defining its C enum value in uAPI.
|
|
type: string
|
|
doc:
|
|
description: Documentation for the command.
|
|
type: string
|
|
value:
|
|
description: Value for the enum in the uAPI.
|
|
$ref: '#/$defs/uint'
|
|
attribute-set:
|
|
description: |
|
|
Attribute space from which attributes directly in the requests and replies
|
|
to this command are defined.
|
|
type: string
|
|
flags: &cmd_flags
|
|
description: Command flags.
|
|
type: array
|
|
items:
|
|
enum: [ admin-perm ]
|
|
dont-validate:
|
|
description: Kernel attribute validation flags.
|
|
type: array
|
|
items:
|
|
enum: [ strict, dump ]
|
|
# Start genetlink-legacy
|
|
fixed-header: *fixed-header
|
|
# End genetlink-legacy
|
|
do: &subop-type
|
|
description: Main command handler.
|
|
type: object
|
|
additionalProperties: False
|
|
properties:
|
|
request: &subop-attr-list
|
|
description: Definition of the request message for a given command.
|
|
type: object
|
|
additionalProperties: False
|
|
properties:
|
|
attributes:
|
|
description: |
|
|
Names of attributes from the attribute-set (not full attribute
|
|
definitions, just names).
|
|
type: array
|
|
items:
|
|
type: string
|
|
# Start genetlink-legacy
|
|
value:
|
|
description: |
|
|
ID of this message if value for request and response differ,
|
|
i.e. requests and responses have different message enums.
|
|
$ref: '#/$defs/uint'
|
|
# End genetlink-legacy
|
|
reply: *subop-attr-list
|
|
pre:
|
|
description: Hook for a function to run before the main callback (pre_doit or start).
|
|
type: string
|
|
post:
|
|
description: Hook for a function to run after the main callback (post_doit or done).
|
|
type: string
|
|
dump: *subop-type
|
|
notify:
|
|
description: Name of the command sharing the reply type with this notification.
|
|
type: string
|
|
event:
|
|
type: object
|
|
additionalProperties: False
|
|
properties:
|
|
attributes:
|
|
description: Explicit list of the attributes for the notification.
|
|
type: array
|
|
items:
|
|
type: string
|
|
mcgrp:
|
|
description: Name of the multicast group generating given notification.
|
|
type: string
|
|
mcast-groups:
|
|
description: List of multicast groups.
|
|
type: object
|
|
required: [ list ]
|
|
additionalProperties: False
|
|
properties:
|
|
list:
|
|
description: List of groups.
|
|
type: array
|
|
items:
|
|
type: object
|
|
required: [ name ]
|
|
additionalProperties: False
|
|
properties:
|
|
name:
|
|
description: |
|
|
The name for the group, used to form the define and the value of the define.
|
|
type: string
|
|
# Start genetlink-c
|
|
c-define-name:
|
|
description: Override for the name of the define in C uAPI.
|
|
type: string
|
|
# End genetlink-c
|
|
flags: *cmd_flags
|
|
# Start netlink-raw
|
|
value:
|
|
description: Value of the netlink multicast group in the uAPI.
|
|
type: integer
|
|
# End netlink-raw
|