| # 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. |
| |
| Different devices can provide different feature sets, e.g. with no |
| support for complex scheduling hierarchy, or for some shaping |
| parameters. The user can introspect the HW capabilities via the |
| @cap-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 |
| - |
| name: caps |
| attributes: |
| - |
| name: ifindex |
| type: u32 |
| doc: Interface index queried for shapers capabilities. |
| - |
| name: scope |
| type: u32 |
| enum: scope |
| doc: The scope to which the queried capabilities apply. |
| - |
| name: support-metric-bps |
| type: flag |
| doc: The device accepts 'bps' metric for bw-min, bw-max and burst. |
| - |
| name: support-metric-pps |
| type: flag |
| doc: The device accepts 'pps' metric for bw-min, bw-max and burst. |
| - |
| name: support-nesting |
| type: flag |
| doc: | |
| The device supports nesting shaper belonging to this scope |
| below 'node' scoped shapers. Only 'queue' and 'node' |
| scope can have flag 'support-nesting'. |
| - |
| name: support-bw-min |
| type: flag |
| doc: The device supports a minimum guaranteed B/W. |
| - |
| name: support-bw-max |
| type: flag |
| doc: The device supports maximum B/W shaping. |
| - |
| name: support-burst |
| type: flag |
| doc: The device supports a maximum burst size. |
| - |
| name: support-priority |
| type: flag |
| doc: The device supports priority scheduling. |
| - |
| name: support-weight |
| type: flag |
| doc: The device supports weighted round robin scheduling. |
| |
| 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 |
| |
| - |
| name: cap-get |
| doc: | |
| Get the shaper capabilities supported by the given device |
| for the specified scope. |
| attribute-set: caps |
| |
| do: |
| pre: net-shaper-nl-cap-pre-doit |
| post: net-shaper-nl-cap-post-doit |
| request: |
| attributes: |
| - ifindex |
| - scope |
| reply: |
| attributes: &cap-attrs |
| - ifindex |
| - scope |
| - support-metric-bps |
| - support-metric-pps |
| - support-nesting |
| - support-bw-min |
| - support-bw-max |
| - support-burst |
| - support-priority |
| - support-weight |
| |
| dump: |
| pre: net-shaper-nl-cap-pre-dumpit |
| post: net-shaper-nl-cap-post-dumpit |
| request: |
| attributes: |
| - ifindex |
| reply: |
| attributes: *cap-attrs |
