mirror of
https://github.com/torvalds/linux.git
synced 2026-05-30 00:29:35 +08:00
fbf5df34a4
Using definitions in kernel policies is awkward right now. On one hand we want defines for max values and such. On the other we don't have a way of adding kernel-only defines. Adding unnecessary defines to uAPI is a bad idea, we won't be able to delete them. And when it comes to policy user space should just query it via the policy dump, not use hard coded defines. Add a "scope" property to definitions, which will let us tell the codegen that a definition is for kernel use only. Support following values: - uapi: render into the uAPI header (default, today's behavior) - kernel: render to kernel header only - user: same as kernel but for the user-side generated header Definitions may have a header property (definition is "external", provided by existing header). Extend the scope to headers, too. If definition has both scope and header properties we will only generate the includes in the right scope. Signed-off-by: Jakub Kicinski <kuba@kernel.org> Link: https://patch.msgid.link/20260510192904.3987113-8-kuba@kernel.org Signed-off-by: Paolo Abeni <pabeni@redhat.com>
363 lines
13 KiB
YAML
363 lines
13 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-legacy.yaml#
|
|
$schema: https://json-schema.org/draft-07/schema
|
|
|
|
# Common defines
|
|
$defs:
|
|
name:
|
|
type: string
|
|
pattern: ^[0-9a-z-]+$
|
|
uint:
|
|
type: integer
|
|
minimum: 0
|
|
len-or-define:
|
|
type: [ string, integer ]
|
|
pattern: ^[0-9A-Za-z_-]+( - 1)?$
|
|
minimum: 0
|
|
len-or-limit:
|
|
# literal int, const name, or limit based on fixed-width type
|
|
# e.g. u8-min, u16-max, etc.
|
|
type: [ string, integer ]
|
|
pattern: ^[0-9A-Za-z_-]+$
|
|
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.
|
|
$ref: '#/$defs/name'
|
|
doc:
|
|
type: string
|
|
protocol:
|
|
description: Schema compatibility level. Default is "genetlink".
|
|
enum: [ genetlink ]
|
|
uapi-header:
|
|
description: Path to the uAPI header, default is linux/${family-name}.h
|
|
type: string
|
|
|
|
definitions:
|
|
description: List of type and constant definitions (enums, flags, defines).
|
|
type: array
|
|
items:
|
|
type: object
|
|
required: [ type, name ]
|
|
additionalProperties: False
|
|
properties:
|
|
name:
|
|
$ref: '#/$defs/name'
|
|
header:
|
|
description: For C-compatible languages, header which already defines this value.
|
|
type: string
|
|
scope:
|
|
description: |
|
|
Visibility of this definition. "uapi" (default) renders into
|
|
the uAPI header, "kernel" renders into the kernel-side
|
|
generated header, "user" renders into the user-side
|
|
generated header. When combined with `header:`, the
|
|
definition is not rendered, and the named header is
|
|
included only by code matching the scope.
|
|
enum: [ uapi, kernel, user ]
|
|
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:
|
|
$ref: '#/$defs/name'
|
|
value:
|
|
type: integer
|
|
doc:
|
|
type: string
|
|
render-max:
|
|
description: Render the max members for this enum.
|
|
type: boolean
|
|
|
|
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.
|
|
$ref: '#/$defs/name'
|
|
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
|
|
attributes:
|
|
description: List of attributes in the space.
|
|
type: array
|
|
items:
|
|
type: object
|
|
required: [ name ]
|
|
additionalProperties: False
|
|
properties:
|
|
name:
|
|
$ref: '#/$defs/name'
|
|
type: &attr-type
|
|
enum: [ unused, pad, flag, binary,
|
|
uint, sint, u8, u16, u32, u64, s8, s16, 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'
|
|
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, ipv4-or-v6, uuid ]
|
|
|
|
# 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.
|
|
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
|
|
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.
|
|
$ref: '#/$defs/name'
|
|
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, uns-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.
|
|
$ref: '#/$defs/name'
|
|
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
|