400 lines
14 KiB
YAML
400 lines
14 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/genetlink-c.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
|
|
len-or-limit:
|
|
# literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc.
|
|
type: [ string, integer ]
|
|
pattern: ^[su](8|16|32|64)-(min|max)$
|
|
minimum: 0
|
|
|
|
# Schema for specs
|
|
title: Protocol
|
|
description: Specification of a genetlink protocol
|
|
type: object
|
|
required: [ name, doc, attribute-sets, operations ]
|
|
additionalProperties: False
|
|
properties:
|
|
name:
|
|
description: Name of the genetlink family.
|
|
type: string
|
|
doc:
|
|
type: string
|
|
protocol:
|
|
description: Schema compatibility level. Default is "genetlink".
|
|
enum: [ genetlink, genetlink-c ]
|
|
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
|
|
|
|
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 ]
|
|
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
|
|
|
|
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, if empty no name will be used.
|
|
type: [ string, "null" ]
|
|
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
|
|
enum: [ unused, pad, flag, binary,
|
|
uint, sint, u8, u16, u32, u64, s32, s64,
|
|
string, nest, indexed-array, 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.
|
|
$ref: '#/$defs/len-or-limit'
|
|
max:
|
|
description: Max value for an integer attribute.
|
|
$ref: '#/$defs/len-or-limit'
|
|
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'
|
|
unterminated-ok:
|
|
description: |
|
|
For string attributes, do not check whether attribute
|
|
contains the terminating null character.
|
|
type: boolean
|
|
sub-type: *attr-type
|
|
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 ]
|
|
# Start genetlink-c
|
|
name-prefix:
|
|
type: string
|
|
# End genetlink-c
|
|
|
|
# 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 ]
|
|
|
|
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 ]
|
|
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, if empty no name will be used.
|
|
type: [ string, "null" ]
|
|
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 commands, if empty no name will be used.
|
|
type: [ string, "null" ]
|
|
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, dump-strict ]
|
|
config-cond:
|
|
description: |
|
|
Name of the kernel config option gating the presence of
|
|
the operation, without the 'CONFIG_' prefix.
|
|
type: string
|
|
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
|
|
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
|
|
|
|
kernel-family:
|
|
description: Additional global attributes used for kernel C code generation.
|
|
type: object
|
|
additionalProperties: False
|
|
properties:
|
|
headers:
|
|
description: |
|
|
List of extra headers which should be included in the source
|
|
of the generated code.
|
|
type: array
|
|
items:
|
|
type: string
|
|
sock-priv:
|
|
description: |
|
|
Literal name of the type which is used within the kernel
|
|
to store the socket state. The type / structure is internal
|
|
to the kernel, and is not defined in the spec.
|
|
type: string
|