The Linux Kernel Logo
  • 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
        • AF_XDP
        • Bare UDP Tunnelling Module Documentation
        • batman-adv
        • SocketCAN - Controller Area Network
        • The UCAN Protocol
        • Hardware Device Drivers
        • Networking Diagnostics
        • Distributed Switch Architecture
        • Linux Devlink Documentation
        • CAIF
        • Netlink interface for ethtool
        • IEEE 802.15.4 Developer’s Guide
        • ISO 15765-2 (ISO-TP)
        • J1939 Documentation
        • Linux Networking and Network Devices APIs
        • MSG_ZEROCOPY
        • FAILOVER
        • Net DIM - Generic Network Dynamic Interrupt Moderation
        • NET_FAILOVER
        • Page Pool API
        • PHY Abstraction Layer
        • phylink
        • IP-Aliasing
        • Ethernet Bridging
        • SNMP counter
        • Checksum Offloads
        • Segmentation Offloads
        • Scaling in the Linux Networking Stack
        • Kernel TLS
        • Kernel TLS offload
        • In-Kernel TLS Handshake
        • Linux NFC subsystem
        • Netdev private dataroom for 6lowpan interfaces
        • 6pack Protocol
        • ARCnet Hardware
        • ARCnet
        • ATM
        • AX.25
        • Linux Ethernet Bonding Driver HOWTO
        • cdc_mbim - Driver for CDC MBIM Mobile Broadband modems
        • DCCP protocol
        • DCTCP (DataCenter TCP)
        • Device Memory TCP
        • DNS Resolver Module
        • Softnet Driver Issues
        • EQL Driver: Serial IP Load Balancing HOWTO
        • LC-trie implementation notes
        • Linux Socket Filtering aka Berkeley Packet Filter (BPF)
        • Generic HDLC layer
        • Generic Netlink
        • Netlink Family Specifications
          • Family conntrack netlink specification
          • Family devlink netlink specification
          • Family dpll netlink specification
          • Family ethtool netlink specification
          • Family fou netlink specification
          • Family handshake netlink specification
          • Family lockd netlink specification
          • Family mptcp_pm netlink specification
          • Family net-shaper netlink specification
            • Summary
            • Operations
              • get
              • set
              • delete
              • group
              • cap-get
            • Definitions
              • scope
              • metric
            • Attribute sets
              • net-shaper
                • handle (nest)
                • metric (u32)
                • bw-min (uint)
                • bw-max (uint)
                • burst (uint)
                • priority (u32)
                • weight (u32)
                • ifindex (u32)
                • parent (nest)
                • leaves (nest)
              • handle
                • scope (u32)
                • id (u32)
              • leaf-info
                • handle
                • priority
                • weight
              • caps
                • ifindex (u32)
                • scope (u32)
                • support-metric-bps (flag)
                • support-metric-pps (flag)
                • support-nesting (flag)
                • support-bw-min (flag)
                • support-bw-max (flag)
                • support-burst (flag)
                • support-priority (flag)
                • support-weight (flag)
          • Family netdev netlink specification
          • Family nfsd netlink specification
          • Family nftables netlink specification
          • Family nl80211 netlink specification
          • Family nlctrl netlink specification
          • Family ovs_datapath netlink specification
          • Family ovs_flow netlink specification
          • Family ovs_vport netlink specification
          • Family rt-addr netlink specification
          • Family rt-link netlink specification
          • Family rt-neigh netlink specification
          • Family rt-route netlink specification
          • Family rt-rule netlink specification
          • Family tc netlink specification
          • Family tcp_metrics netlink specification
          • Family team netlink specification
        • Generic networking statistics for netlink users
        • The Linux kernel GTP tunneling module
        • Identifier Locator Addressing (ILA)
        • IOAM6 Sysfs variables
        • io_uring zero copy Rx
        • IP dynamic address hack-port v0.03
        • IPsec
        • IP Sysctl
        • IPv6
        • IPVLAN Driver HOWTO
        • IPvs-sysctl
        • Kernel Connection Multiplexor
        • L2TP
        • The Linux LAPB Module Interface
        • How to use packet injection with mac80211
        • Management Component Transport Protocol (MCTP)
        • MPLS Sysfs variables
        • Multipath TCP (MPTCP)
        • MPTCP Sysfs variables
        • HOWTO for multiqueue network device support
        • Multi-PF Netdev
        • NAPI
        • Common Networking Struct Cachelines
        • Netconsole
        • Netdev features mess and how to get out from it alive
        • Network Devices, the Kernel, and You!
        • Netfilter Sysfs variables
        • NETIF Msg Level
        • Netmem Support for Network Drivers
        • Resilient Next-hop Groups
        • Netfilter Conntrack Sysfs variables
        • Netfilter’s flowtable infrastructure
        • OPEN Alliance 10BASE-T1x MAC-PHY Serial Interface (TC6) Framework Support
        • Open vSwitch datapath developer documentation
        • Operational States
        • Packet MMAP
        • Linux Phonet protocol family
        • PHY link topology
        • HOWTO for the linux packet generator
        • PLIP: The Parallel Line Internet Protocol Device
        • PPP Generic Driver and Channel Interface
        • The proc/net/tcp and proc/net/tcp6 variables
        • Power Sourcing Equipment (PSE) Documentation
        • How to use radiotap headers
        • RDS
        • Linux wireless regulatory documentation
        • Network Function Representors
        • RxRPC Network Protocol
        • SOCKET OPTIONS
        • SECURITY
        • EXAMPLE CLIENT USAGE
        • Linux Kernel SCTP
        • LSM/SeLinux secid
        • Seg6 Sysfs variables
        • struct sk_buff
        • SMC Sysctl
        • NIC SR-IOV APIs
        • Interface statistics
        • Stream Parser (strparser)
        • Ethernet switch device driver model (switchdev)
        • Sysfs tagging
        • TC Actions - Environmental Rules
        • TC queue based filtering
        • TCP Authentication Option Linux implementation (RFC5925)
        • Thin-streams and TCP
        • Team
        • Timestamping
        • Linux Kernel TIPC
        • Transparent proxy support
        • Universal TUN/TAP device driver
        • The UDP-Lite protocol (RFC 3828)
        • Virtual Routing and Forwarding (VRF)
        • Virtual eXtensible Local Area Networking documentation
        • Linux X.25 Project
        • X.25 Device Driver Interface
        • XFRM device - offloading the IPsec computations
        • XFRM proc - /proc/net/xfrm_* files
        • XFRM
        • XFRM Syscall
        • XDP RX Metadata
        • AF_XDP TX Metadata
      • 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
The Linux Kernel
  • Kernel subsystem documentation
  • Networking
  • Netlink Family Specifications
  • Family net-shaper netlink specification
  • View page 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.

Previous Next

© Copyright The kernel development community.

Built with Sphinx using a theme provided by Read the Docs.