| Message ID | 20230823114202.5862-3-donald.hunter@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | tools/net/ynl: Add support for netlink-raw families | expand |
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@gmail.com> > --- > 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
Jacob Keller <jacob.e.keller@intel.com> writes: > 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@gmail.com> >> --- >> 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? It's a good question. The schema definitions are currently strict supersets of genetlink: genetlink <= genetlink-c <= genetlink-legacy <= netlink-raw As you noted below, there's only 2 additions needed for the netlink raw families, protonum and mcast-group value. I would be happy to change the description and other references to genetlink in this spec, but I'd like to hear Jakub's thoughts about minimal modification vs a more thorough rewording. Perhaps a middle ground would be to extend the top-level description to say "genetlink or raw netlink" and qualify that all mention of genetlink also applies to raw netlink. Either way, I just noticed that the schema $id does need to be updated. >> +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? Raw netlink is, so far, the same as genetlink-legacy with the addition of hard-coded protocol ids. >> + protonum: >> + description: Protocol number to use for netlink-raw >> + type: integer >> + # End netlink-raw [...] >> + # Start netlink-raw >> + value: >> + description: Value of the netlink multicast group in the uAPI. >> + type: integer >> + # End netlink-raw
On 8/23/2023 2:19 PM, Donald Hunter wrote: > Jacob Keller <jacob.e.keller@intel.com> writes: >> On 8/23/2023 4:41 AM, Donald Hunter wrote: >>> +--- >>> +$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? > > It's a good question. The schema definitions are currently strict > supersets of genetlink: > > genetlink <= genetlink-c <= genetlink-legacy <= netlink-raw > > As you noted below, there's only 2 additions needed for the netlink raw > families, protonum and mcast-group value. > > I would be happy to change the description and other references to > genetlink in this spec, but I'd like to hear Jakub's thoughts about > minimal modification vs a more thorough rewording. Perhaps a middle > ground would be to extend the top-level description to say "genetlink or > raw netlink" and qualify that all mention of genetlink also applies to > raw netlink. > > Either way, I just noticed that the schema $id does need to be updated. > Ok, ya lets wait for Jakub's opinion. I think the clarification would be good since at least conceptually genetlink is distinct to me from netlink raw, so it feels a bit weird. Either way, they share far more in common than I had originally realized, so its not a huge deal. Thanks for the clarification! >>> +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? > > Raw netlink is, so far, the same as genetlink-legacy with the addition > of hard-coded protocol ids. > Right that makes sense why this shares so much. Thanks, Jake
On Wed, 23 Aug 2023 14:43:13 -0700 Jacob Keller wrote: > > It's a good question. The schema definitions are currently strict > > supersets of genetlink: > > > > genetlink <= genetlink-c <= genetlink-legacy <= netlink-raw > > > > As you noted below, there's only 2 additions needed for the netlink raw > > families, protonum and mcast-group value. > > > > I would be happy to change the description and other references to > > genetlink in this spec, but I'd like to hear Jakub's thoughts about > > minimal modification vs a more thorough rewording. Perhaps a middle > > ground would be to extend the top-level description to say "genetlink or > > raw netlink" and qualify that all mention of genetlink also applies to > > raw netlink. > > > > Either way, I just noticed that the schema $id does need to be updated. > > Ok, ya lets wait for Jakub's opinion. I think the clarification would be > good since at least conceptually genetlink is distinct to me from > netlink raw, so it feels a bit weird. Hm, no great choice here. I feel like posterity may judge us if we don't clean up the genetlink references so let's remove the most obvious ones. description, name.description, delete version completely, narrow down protocol to just netlink-raw. And I think that's it? The comments are fine, IMO.
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 +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 + 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
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. Signed-off-by: Donald Hunter <donald.hunter@gmail.com> --- Documentation/netlink/netlink-raw.yaml | 414 +++++++++++++++++++++++++ 1 file changed, 414 insertions(+) create mode 100644 Documentation/netlink/netlink-raw.yaml