doc/netlink: Add a schema for netlink-raw families
This schema is largely a copy of the genetlink-legacy schema with the following modifications: - change the schema id to netlink-raw - add a top-level protonum property, e.g. 0 (for NETLINK_ROUTE) - change the protocol enumeration to netlink-raw, removing the genetlink options. - replace doc references to generic netlink with raw netlink - add a value property to mcast-group definitions Signed-off-by: Donald Hunter <donald.hunter@gmail.com> Reviewed-by: Jacob Keller <jacob.e.keller@intel.com> Link: https://lore.kernel.org/r/20230825122756.7603-3-donald.hunter@gmail.com Signed-off-by: Jakub Kicinski <kuba@kernel.org>
This commit is contained in:
Donald Hunter
Jakub Kicinski
parent
c4e1ab07b5
commit
ed68c58c0e
|
|
@ -0,0 +1,410 @@
|
|||
# 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
|
||||
# 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
|
||||
enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ]
|
||||
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 ]
|
||||
# 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, type ]
|
||||
additionalProperties: False
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
type: &attr-type
|
||||
description: The netlink attribute type
|
||||
enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64,
|
||||
string, nest, array-nest, nest-type-value ]
|
||||
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'
|
||||
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
|
||||
|
||||
# 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 ]
|
||||
|
||||
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
|
||||
Loading…
Reference in New Issue