.. LINENO 1

.. SPDX-License-Identifier: GPL-2.0
.. NOTE: This document was auto-generated.


.. _netlink-net-shaper:


===========================================
Family ``net-shaper`` netlink specification
===========================================


.. contents:: :depth: 3


-------
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
----------


.. LINENO 206

.. _net-shaper-operation-get:

get
===
Get information about a shaper for a given device.


:attribute-set: :ref:`net-shaper-attribute-set-net-shaper`
:do:
.. LINENO 212

    **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:
.. LINENO 231

    **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``]



.. LINENO 239

.. _net-shaper-operation-set:

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: :ref:`net-shaper-attribute-set-net-shaper`
:flags: [``admin-perm``]
:do:
.. LINENO 248

    **pre**
        net-shaper-nl-pre-doit

    **post**
        net-shaper-nl-post-doit

    **request**
        :attributes: [``ifindex``, ``handle``, ``metric``, ``bw-min``, ``bw-max``, ``burst``, ``priority``, ``weight``]



.. LINENO 262

.. _net-shaper-operation-delete:

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: :ref:`net-shaper-attribute-set-net-shaper`
:flags: [``admin-perm``]
:do:
.. LINENO 279

    **pre**
        net-shaper-nl-pre-doit

    **post**
        net-shaper-nl-post-doit

    **request**
        :attributes: [``ifindex``, ``handle``]



.. LINENO 285

.. _net-shaper-operation-group:

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: :ref:`net-shaper-attribute-set-net-shaper`
:flags: [``admin-perm``]
:do:
.. LINENO 310

    **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``]



.. LINENO 328

.. _net-shaper-operation-cap-get:

cap-get
=======
Get the shaper capabilities supported by the given device
for the specified scope.


:attribute-set: :ref:`net-shaper-attribute-set-caps`
:do:
.. LINENO 335

    **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:
.. LINENO 355

    **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
-----------


.. LINENO 35

.. _net-shaper-definition-scope:

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.


.. LINENO 59

.. _net-shaper-definition-metric:

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-attribute-set-net-shaper:

net-shaper
==========
.. LINENO 75

handle (``nest``)
~~~~~~~~~~~~~~~~~
:nested-attributes: :ref:`net-shaper-attribute-set-handle`
:doc: Unique identifier for the given shaper inside the owning device.


.. LINENO 80

metric (``u32``)
~~~~~~~~~~~~~~~~
:enum: :ref:`net-shaper-definition-metric`
:doc: Metric used by the given shaper for bw-min, bw-max and burst.


.. LINENO 85

bw-min (``uint``)
~~~~~~~~~~~~~~~~~
:doc: Guaranteed bandwidth for the given shaper.


.. LINENO 89

bw-max (``uint``)
~~~~~~~~~~~~~~~~~
:doc: Maximum bandwidth for the given shaper or 0 when unlimited.


.. LINENO 93

burst (``uint``)
~~~~~~~~~~~~~~~~
:doc: Maximum burst-size for shaping. Should not be interpreted as a quantum.


.. LINENO 99

priority (``u32``)
~~~~~~~~~~~~~~~~~~
:doc: Scheduling priority for the given shaper. The priority scheduling is applied to sibling shapers.


.. LINENO 105

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.


.. LINENO 113

ifindex (``u32``)
~~~~~~~~~~~~~~~~~
:doc: Interface index owning the specified shaper.


.. LINENO 117

parent (``nest``)
~~~~~~~~~~~~~~~~~
:nested-attributes: :ref:`net-shaper-attribute-set-handle`
:doc: Identifier for the parent of the affected shaper. Only needed for @group operation.


.. LINENO 124

leaves (``nest``)
~~~~~~~~~~~~~~~~~
:multi-attr: True
:nested-attributes: :ref:`net-shaper-attribute-set-leaf-info`
:doc: Describes a set of leaves shapers for a @group operation.


.. _net-shaper-attribute-set-handle:

handle
======
.. LINENO 134

scope (``u32``)
~~~~~~~~~~~~~~~
:enum: :ref:`net-shaper-definition-scope`
:doc: Defines the shaper @id interpretation.


.. LINENO 139

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.


.. _net-shaper-attribute-set-leaf-info:

leaf-info
=========
.. LINENO 150

handle
~~~~~~


.. LINENO 152

priority
~~~~~~~~


.. LINENO 154

weight
~~~~~~


.. _net-shaper-attribute-set-caps:

caps
====
.. LINENO 159

ifindex (``u32``)
~~~~~~~~~~~~~~~~~
:doc: Interface index queried for shapers capabilities.


.. LINENO 163

scope (``u32``)
~~~~~~~~~~~~~~~
:enum: :ref:`net-shaper-definition-scope`
:doc: The scope to which the queried capabilities apply.


.. LINENO 168

support-metric-bps (``flag``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The device accepts 'bps' metric for bw-min, bw-max and burst.


.. LINENO 172

support-metric-pps (``flag``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The device accepts 'pps' metric for bw-min, bw-max and burst.


.. LINENO 176

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'.


.. LINENO 183

support-bw-min (``flag``)
~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The device supports a minimum guaranteed B/W.


.. LINENO 187

support-bw-max (``flag``)
~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The device supports maximum B/W shaping.


.. LINENO 191

support-burst (``flag``)
~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The device supports a maximum burst size.


.. LINENO 195

support-priority (``flag``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The device supports priority scheduling.


.. LINENO 199

support-weight (``flag``)
~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The device supports weighted round robin scheduling.