On 8/23/2023 4:41 AM, Donald Hunter wrote: > This schema is largely a copy of the genetlink-legacy schema with the > following additions: > > - a top-level protonum property, e.g. 0 (for NETLINK_ROUTE) > - add netlink-raw to the list of protocols supported by the schema > - add a value property to mcast-group definitions > > This schema is very similar to genetlink-legacy and I considered > making the changes there and symlinking to it. On balance I felt that > might be problematic for accurate schema validation. > Ya, I think they have to be distinct to properly validate. > Signed-off-by: Donald Hunter <donald.hunter@xxxxxxxxx> > --- > Documentation/netlink/netlink-raw.yaml | 414 +++++++++++++++++++++++++ > 1 file changed, 414 insertions(+) > create mode 100644 Documentation/netlink/netlink-raw.yaml > > diff --git a/Documentation/netlink/netlink-raw.yaml b/Documentation/netlink/netlink-raw.yaml > new file mode 100644 > index 000000000000..ef7bd07eab62 > --- /dev/null > +++ b/Documentation/netlink/netlink-raw.yaml > @@ -0,0 +1,414 @@ > +# 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: > + 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 genetlink protocol If this is for netlink-raw, shouldn't this not say genetlink? Same elsewhere? or am I misunderstanding something? > +type: object > +required: [ name, doc, attribute-sets, operations ] > +additionalProperties: False > +properties: > + name: > + description: Name of the genetlink family. > + type: string > + doc: > + type: string > + version: > + description: Generic Netlink family version. Default is 1. > + type: integer > + minimum: 1 > + protocol: > + description: Schema compatibility level. Default is "genetlink". > + enum: [ genetlink, genetlink-c, genetlink-legacy, netlink-raw ] # Trim > + # Start netlink-raw I guess the netlink raw part is only below this? Or does netlink raw share more of the generic netlink code than I thought? > + 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
