linux/Documentation/netlink/netlink-raw.yaml
Donald Hunter bf08f32c8c tools/net/ynl: Add support for nested structs
Make it possible for struct definitions to reference other struct
definitions ofr binary members. For example, the tbf qdisc uses this
struct definition for its parms attribute:

  -
    name: tc-tbf-qopt
    type: struct
    members:
      -
        name: rate
        type: binary
        struct: tc-ratespec
      -
        name: peakrate
        type: binary
        struct: tc-ratespec
      -
        name: limit
        type: u32
      -
        name: buffer
        type: u32
      -
        name: mtu
        type: u32

This adds the necessary schema changes and adds nested struct encoding
and decoding to ynl.

Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Reviewed-by: Jiri Pirko <jiri@nvidia.com>
Link: https://lore.kernel.org/r/20240129223458.52046-11-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2024-01-31 21:19:19 -08:00

501 lines
18 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 ]
struct:
description: Name of the nested struct type.
type: string
if:
properties:
type:
const: pad
then:
required: [ len ]
if:
properties:
type:
const: binary
then:
oneOf:
- required: [ len ]
- required: [ struct ]
# 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