Re: [PATCH v6 net-next 02/15] netlink: spec: add shaper YAML spec

[Jakub Kicinski <kuba@kernel.org>]

On Wed,  4 Sep 2024 15:53:34 +0200 Paolo Abeni wrote:
> +doc: |
> +  Networking HW rate limiting configuration.
> +
> +  This API allows configuring HW shapers available on the network
> +  devices at different levels (queues, network device) and allows
> +  arbitrary manipulation of the scheduling tree of the involved
> +  shapers.
> +
> +  Each @shaper is identified within the given device, by an @handle,
> +  comprising both a @scope and an @id.
> +
> +  Depending on the @scope value, the shapers are attached to specific
> +  HW objects (queues, devices) or, for @node scope, represent a
> +  scheduling group, that can be placed in an arbitrary location of
> +  the scheduling tree.
> +
> +  Shapers can be created with two different operations: the @set
> +  operation, to create and update a single "attached" shaper, and
> +  the @group operation, to create and update a scheduling
> +  group. Only the @group operation can create @node scope shapers
> +
> +  Existing shapers can be deleted /reset via the @delete operation.

nit: space before the / ?

> +        name: bw-min
> +        type: uint
> +        doc: Minimum Guaranteed bandwidth for the given shaper.

I think I asked to remove "Minimum"? Both "guaranteed" and "minimum"
express the fact that we can't go lower, so it's a bit of a pleonasm.

> +      -
> +        name: node
> +        type: nest
> +        nested-attributes: node-info
> +        doc: |
> +           Describes the node shaper for a @group operation.
> +           Differently from @leaves and @shaper allow specifying
> +           the shaper parent handle, too.

Parent handle is inside node scope? Why are leaves outside and parent
inside? Both should be at the same scope, preferably main scope.

> +      -
> +        name: shaper
> +        type: nest
> +        nested-attributes: info
> +        doc: |
> +           Describes a single shaper for a @set operation.

Why does this level of nesting exist? With the exception of ifindex 
all attributes for SET are nested inside this..