Logo

The Linux Kernel

6.15.0

Quick search

Contents

  • Development process
  • Submitting patches
  • Code of conduct
  • Maintainer handbook
  • All development-process docs
  • Core API
  • Driver APIs
  • Subsystems
    • Core subsystems
    • Human interfaces
    • Networking interfaces
      • Networking
      • NetLabel
      • InfiniBand
      • ISDN
      • MHI
    • Storage interfaces
    • Other subsystems
  • Locking
  • Licensing rules
  • Writing documentation
  • Development tools
  • Testing guide
  • Hacking guide
  • Tracing
  • Fault injection
  • Livepatching
  • Rust
  • Administration
  • Build system
  • Reporting issues
  • Userspace tools
  • Userspace API
  • Firmware
  • Firmware and Devicetree
  • CPU architectures
  • Unsorted documentation
  • Translations

This Page

  • Show Source

Family net-shaper netlink specification¶

Contents

  • Family net-shaper netlink specification

    • Summary

    • Operations

      • get

      • set

      • delete

      • group

      • cap-get

    • Definitions

      • scope

      • metric

    • Attribute sets

      • net-shaper

      • handle

      • leaf-info

      • caps

Summary¶

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.

Operations¶

get¶

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

[ifindex, handle]

reply
attributes

[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

[ifindex, parent, handle, metric, bw-min, bw-max, burst, priority, weight]

set¶

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]

delete¶

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

[ifindex, handle]

group¶

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

[ifindex, handle]

cap-get¶

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

[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

[ifindex, scope, support-metric-bps, support-metric-pps, support-nesting, support-bw-min, support-bw-max, support-burst, support-priority, support-weight]

Definitions¶

scope¶

type

enum

doc

Defines the shaper @id interpretation.

entries
unspec

The scope is not specified.

netdev

The main shaper for the given network device.

queue

The shaper is attached to the given device queue, the @id represents the queue number.

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.

metric¶

type

enum

doc

Different metric supported by the shaper.

entries
bps

Shaper operates on a bits per second basis.

pps

Shaper operates on a packets per second basis.

Attribute sets¶

net-shaper¶

handle (nest)¶

nested-attributes

handle

doc

Unique identifier for the given shaper inside the owning device.

metric (u32)¶

enum

metric

doc

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

bw-min (uint)¶

doc

Guaranteed bandwidth for the given shaper.

bw-max (uint)¶

doc

Maximum bandwidth for the given shaper or 0 when unlimited.

burst (uint)¶

doc

Maximum burst-size for shaping. Should not be interpreted as a quantum.

priority (u32)¶

doc

Scheduling priority for the given shaper. The priority scheduling is applied to sibling shapers.

weight (u32)¶

doc

Relative weight for round robin scheduling of the given shaper. The scheduling is applied to all sibling shapers with the same priority.

ifindex (u32)¶

doc

Interface index owning the specified shaper.

parent (nest)¶

nested-attributes

handle

doc

Identifier for the parent of the affected shaper. Only needed for @group operation.

leaves (nest)¶

multi-attr

True

nested-attributes

leaf-info

doc

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

handle¶

scope (u32)¶

enum

scope

doc

Defines the shaper @id interpretation.

id (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.

leaf-info¶

handle¶

priority¶

weight¶

caps¶

ifindex (u32)¶

doc

Interface index queried for shapers capabilities.

scope (u32)¶

enum

scope

doc

The scope to which the queried capabilities apply.

support-metric-bps (flag)¶

doc

The device accepts ‘bps’ metric for bw-min, bw-max and burst.

support-metric-pps (flag)¶

doc

The device accepts ‘pps’ metric for bw-min, bw-max and burst.

support-nesting (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’.

support-bw-min (flag)¶

doc

The device supports a minimum guaranteed B/W.

support-bw-max (flag)¶

doc

The device supports maximum B/W shaping.

support-burst (flag)¶

doc

The device supports a maximum burst size.

support-priority (flag)¶

doc

The device supports priority scheduling.

support-weight (flag)¶

doc

The device supports weighted round robin scheduling.

©The kernel development community. | Powered by Sphinx 3.4.3 & Alabaster 0.7.12 | Page source