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

[Jakub Kicinski <kuba@kernel.org>]

On Mon, 30 Sep 2024 15:53:49 +0200 Paolo Abeni wrote:
> +      name: group
> +      doc: |
> +        Create or update a scheduling group, attaching the specified
> +        @leaves shapers under the specified node identified by @handle,
> +        creating the latter, if needed.

This line is unnecessary? The first line already says "create or update"
so no need to say again that the node will be created?

> +        The @leaves shapers scope must be @queue and the node shaper
> +        scope must be either @node or @netdev.
> +        When the node shaper has @node scope, if the @handle @id is not
> +        specified, a new shaper of such scope is created, otherwise the
> +        specified node must already exist.

> +        The @parent handle for the node shaper is optional in most cases.
> +        For newly created node scope shaper, the node parent is set by
> +        default to the parent linked to the @leaves before the @group
> +        operation. If, prior to the grouping operation, the @leaves
> +        have different parents, the node shaper @parent must be explicitly
> +        set.

How about:

	The @parent handle for a new node shaper defaults to the parent
	of all the leaves, provided all the leaves share the same parent.
	Otherwise @parent handle must be specified.

> +        The user can optionally provide shaping attributes for the node
> +        shaper.
> +        The operation is atomic, on failure no change is applied to
> +        the device shaping configuration, otherwise the @node shaper
> +        full identifier, comprising @binding and @handle, is provided
> +        as the reply.

We should also mention that if the node already exists the group
operation will _add_ leaves to it, rather than recreating it with
the provided set of leaves. Right? My intuition was that the node
will get the specified set of leaves and the other leaves get deleted.
The current behavior is fine, but needs to be documented.