Commit 04e65df9 authored by Paolo Abeni's avatar Paolo Abeni Committed by Jakub Kicinski
Browse files

netlink: spec: add shaper YAML spec 



Define the user-space visible interface to query, configure and delete
network shapers via yaml definition.

Add dummy implementations for the relevant NL callbacks.

set() and delete() operations touch a single shaper creating/updating or
deleting it.
The group() operation creates a shaper's group, nesting multiple input
shapers under the specified output shaper.

Reviewed-by: default avatarJiri Pirko <jiri@nvidia.com>
Signed-off-by: default avatarPaolo Abeni <pabeni@redhat.com>
Link: https://patch.msgid.link/7a33a1ff370bdbcd0cd3f909575c912cd56f41da.1728460186.git.pabeni@redhat.com


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent 13d68a16

Documentation/netlink/specs/net_shaper.yaml

0 → 100644
+274 −0
Original line number Diff line number Diff line 
# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)

name: net-shaper



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



  The user can query the running configuration via the @get operation.



definitions:

  -

    type: enum

    name: scope

    doc: Defines the shaper @id interpretation.

    render-max: true

    entries:

      - name: unspec

        doc: The scope is not specified.

      -

        name: netdev

        doc: The main shaper for the given network device.

      -

        name: queue

        doc: |

            The shaper is attached to the given device queue,

            the @id represents the queue number.

      -

        name: node

        doc: |

             The shaper allows grouping of queues or other

             node shapers; can be nested in either @netdev

             shapers or other @node shapers, allowing placement

             in any location of the scheduling tree, except

             leaves and root.

  -

    type: enum

    name: metric

    doc: Different metric supported by the shaper.

    entries:

      -

        name: bps

        doc: Shaper operates on a bits per second basis.

      -

        name: pps

        doc: Shaper operates on a packets per second basis.



attribute-sets:

  -

    name: net-shaper

    attributes:

      -

        name: handle

        type: nest

        nested-attributes: handle

        doc: Unique identifier for the given shaper inside the owning device.

      -

        name: metric

        type: u32

        enum: metric

        doc: Metric used by the given shaper for bw-min, bw-max and burst.

      -

        name: bw-min

        type: uint

        doc: Guaranteed bandwidth for the given shaper.

      -

        name: bw-max

        type: uint

        doc: Maximum bandwidth for the given shaper or 0 when unlimited.

      -

        name: burst

        type: uint

        doc: |

          Maximum burst-size for shaping. Should not be interpreted

          as a quantum.

      -

        name: priority

        type: u32

        doc: |

          Scheduling priority for the given shaper. The priority

          scheduling is applied to sibling shapers.

      -

        name: weight

        type: u32

        doc: |

          Relative weight for round robin scheduling of the

          given shaper.

          The scheduling is applied to all sibling shapers

          with the same priority.

      -

        name: ifindex

        type: u32

        doc: Interface index owning the specified shaper.

      -

        name: parent

        type: nest

        nested-attributes: handle

        doc: |

          Identifier for the parent of the affected shaper.

          Only needed for @group operation.

      -

        name: leaves

        type: nest

        multi-attr: true

        nested-attributes: leaf-info

        doc: |

           Describes a set of leaves shapers for a @group operation.

  -

    name: handle

    attributes:

      -

        name: scope

        type: u32

        enum: scope

        doc: Defines the shaper @id interpretation.

      -

        name: id

        type: u32

        doc: |

          Numeric identifier of a shaper. The id semantic depends on

          the scope. For @queue scope it's the queue id and for @node

          scope it's the node identifier.

  -

    name: leaf-info

    subset-of: net-shaper

    attributes:

      -

        name: handle

      -

        name: priority

      -

        name: weight



operations:

  list:

    -

      name: get

      doc: |

        Get information about a shaper for a given device.

      attribute-set: net-shaper



      do:

        pre: net-shaper-nl-pre-doit

        post: net-shaper-nl-post-doit

        request:

          attributes: &ns-binding

            - ifindex

            - handle

        reply:

          attributes: &ns-attrs

            - ifindex

            - parent

            - handle

            - metric

            - bw-min

            - bw-max

            - burst

            - priority

            - weight



      dump:

        pre: net-shaper-nl-pre-dumpit

        post: net-shaper-nl-post-dumpit

        request:

          attributes:

            - ifindex

        reply:

          attributes: *ns-attrs

    -

      name: set

      doc: |

        Create or update the specified shaper.

        The set operation can't be used to create a @node scope shaper,

        use the @group operation instead.

      attribute-set: net-shaper

      flags: [ admin-perm ]



      do:

        pre: net-shaper-nl-pre-doit

        post: net-shaper-nl-post-doit

        request:

          attributes:

            - ifindex

            - handle

            - metric

            - bw-min

            - bw-max

            - burst

            - priority

            - weight



    -

      name: delete

      doc: |

        Clear (remove) the specified shaper. When deleting

        a @node shaper, reattach all the node's leaves to the

        deleted node's parent.

        If, after the removal, the parent shaper has no more

        leaves and the parent shaper scope is @node, the parent

        node is deleted, recursively.

        When deleting a @queue shaper or a @netdev shaper,

        the shaper disappears from the hierarchy, but the

        queue/device can still send traffic: it has an implicit

        node with infinite bandwidth. The queue's implicit node

        feeds an implicit RR node at the root of the hierarchy.

      attribute-set: net-shaper

      flags: [ admin-perm ]



      do:

        pre: net-shaper-nl-pre-doit

        post: net-shaper-nl-post-doit

        request:

          attributes: *ns-binding



    -

      name: group

      doc: |

        Create or update a scheduling group, attaching the specified

        @leaves shapers under the specified node identified by @handle.

        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.

        When updating an existing node shaper, the specified @leaves are

        added to the existing node; such node will also retain any preexisting

        leave.

        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.

      attribute-set: net-shaper

      flags: [ admin-perm ]



      do:

        pre: net-shaper-nl-pre-doit

        post: net-shaper-nl-post-doit

        request:

          attributes:

            - ifindex

            - parent

            - handle

            - metric

            - bw-min

            - bw-max

            - burst

            - priority

            - weight

            - leaves

        reply:

          attributes: *ns-binding

MAINTAINERS

+1 −0
Original line number Diff line number Diff line
@@ -16116,6 +16116,7 @@ F: include/linux/platform_data/wiznet.h 
F:	include/uapi/linux/cn_proc.h

F:	include/uapi/linux/ethtool_netlink.h

F:	include/uapi/linux/if_*

F:	include/uapi/linux/net_shaper.h

F:	include/uapi/linux/netdev*

F:	tools/testing/selftests/drivers/net/

X:	Documentation/devicetree/bindings/net/bluetooth/

include/uapi/linux/net_shaper.h

0 → 100644
+78 −0
Original line number Diff line number Diff line 
/* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) */

/* Do not edit directly, auto-generated from: */

/*	Documentation/netlink/specs/net_shaper.yaml */

/* YNL-GEN uapi header */



#ifndef _UAPI_LINUX_NET_SHAPER_H

#define _UAPI_LINUX_NET_SHAPER_H



#define NET_SHAPER_FAMILY_NAME		"net-shaper"

#define NET_SHAPER_FAMILY_VERSION	1



/**

 * enum net_shaper_scope - Defines the shaper @id interpretation.

 * @NET_SHAPER_SCOPE_UNSPEC: The scope is not specified.

 * @NET_SHAPER_SCOPE_NETDEV: The main shaper for the given network device.

 * @NET_SHAPER_SCOPE_QUEUE: The shaper is attached to the given device queue,

 *   the @id represents the queue number.

 * @NET_SHAPER_SCOPE_NODE: The shaper allows grouping of queues or other node

 *   shapers; can be nested in either @netdev shapers or other @node shapers,

 *   allowing placement in any location of the scheduling tree, except leaves

 *   and root.

 */

enum net_shaper_scope {

	NET_SHAPER_SCOPE_UNSPEC,

	NET_SHAPER_SCOPE_NETDEV,

	NET_SHAPER_SCOPE_QUEUE,

	NET_SHAPER_SCOPE_NODE,



	/* private: */

	__NET_SHAPER_SCOPE_MAX,

	NET_SHAPER_SCOPE_MAX = (__NET_SHAPER_SCOPE_MAX - 1)

};



/**

 * enum net_shaper_metric - Different metric supported by the shaper.

 * @NET_SHAPER_METRIC_BPS: Shaper operates on a bits per second basis.

 * @NET_SHAPER_METRIC_PPS: Shaper operates on a packets per second basis.

 */

enum net_shaper_metric {

	NET_SHAPER_METRIC_BPS,

	NET_SHAPER_METRIC_PPS,

};



enum {

	NET_SHAPER_A_HANDLE = 1,

	NET_SHAPER_A_METRIC,

	NET_SHAPER_A_BW_MIN,

	NET_SHAPER_A_BW_MAX,

	NET_SHAPER_A_BURST,

	NET_SHAPER_A_PRIORITY,

	NET_SHAPER_A_WEIGHT,

	NET_SHAPER_A_IFINDEX,

	NET_SHAPER_A_PARENT,

	NET_SHAPER_A_LEAVES,



	__NET_SHAPER_A_MAX,

	NET_SHAPER_A_MAX = (__NET_SHAPER_A_MAX - 1)

};



enum {

	NET_SHAPER_A_HANDLE_SCOPE = 1,

	NET_SHAPER_A_HANDLE_ID,



	__NET_SHAPER_A_HANDLE_MAX,

	NET_SHAPER_A_HANDLE_MAX = (__NET_SHAPER_A_HANDLE_MAX - 1)

};



enum {

	NET_SHAPER_CMD_GET = 1,

	NET_SHAPER_CMD_SET,

	NET_SHAPER_CMD_DELETE,

	NET_SHAPER_CMD_GROUP,



	__NET_SHAPER_CMD_MAX,

	NET_SHAPER_CMD_MAX = (__NET_SHAPER_CMD_MAX - 1)

};



#endif /* _UAPI_LINUX_NET_SHAPER_H */

net/Kconfig

+3 −0
Original line number Diff line number Diff line
@@ -72,6 +72,9 @@ config NET_DEVMEM 
	depends on GENERIC_ALLOCATOR

	depends on PAGE_POOL



config NET_SHAPER

	bool



menu "Networking options"



source "net/packet/Kconfig"

net/Makefile

+1 −0
Original line number Diff line number Diff line
@@ -79,3 +79,4 @@ obj-$(CONFIG_XDP_SOCKETS) += xdp/ 
obj-$(CONFIG_MPTCP)		+= mptcp/

obj-$(CONFIG_MCTP)		+= mctp/

obj-$(CONFIG_NET_HANDSHAKE)	+= handshake/

obj-$(CONFIG_NET_SHAPER)	+= shaper/