Date: Wed, 23 Aug 2023 12:32:49 -0700
From: Jacob Keller <jacob.e.keller@...el.com>
To: Donald Hunter <donald.hunter@...il.com>, <netdev@...r.kernel.org>, "Jakub
 Kicinski" <kuba@...nel.org>, "David S. Miller" <davem@...emloft.net>, "Eric
 Dumazet" <edumazet@...gle.com>, Paolo Abeni <pabeni@...hat.com>, "Jonathan
 Corbet" <corbet@....net>, <linux-doc@...r.kernel.org>, Stanislav Fomichev
	<sdf@...gle.com>, Arkadiusz Kubalewski <arkadiusz.kubalewski@...el.com>
CC: <donald.hunter@...hat.com>
Subject: Re: [PATCH net-next v4 02/12] doc/netlink: Add a schema for
 netlink-raw families



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@...il.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

Powered by blists - more mailing lists