Documentation/netlink/specs/net_shaper.yaml

   1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
   2 name: net-shaper
   3
   4 doc: |
   5   Networking HW rate limiting configuration.
   6
   7   This API allows configuring HW shapers available on the network
   8   devices at different levels (queues, network device) and allows
   9   arbitrary manipulation of the scheduling tree of the involved
  10   shapers.
  11
  12   Each @shaper is identified within the given device, by a @handle,
  13   comprising both a @scope and an @id.
  14
  15   Depending on the @scope value, the shapers are attached to specific
  16   HW objects (queues, devices) or, for @node scope, represent a
  17   scheduling group, that can be placed in an arbitrary location of
  18   the scheduling tree.
  19
  20   Shapers can be created with two different operations: the @set
  21   operation, to create and update a single "attached" shaper, and
  22   the @group operation, to create and update a scheduling
  23   group. Only the @group operation can create @node scope shapers.
  24
  25   Existing shapers can be deleted/reset via the @delete operation.
  26
  27   The user can query the running configuration via the @get operation.
  28
  29   Different devices can provide different feature sets, e.g. with no
  30   support for complex scheduling hierarchy, or for some shaping
  31   parameters. The user can introspect the HW capabilities via the
  32   @cap-get operation.
  33
  34 definitions:
  35   -
  36     type: enum
  37     name: scope
  38     doc: Defines the shaper @id interpretation.
  39     render-max: true
  40     entries:
  41       - name: unspec
  42         doc: The scope is not specified.
  43       -
  44         name: netdev
  45         doc: The main shaper for the given network device.
  46       -
  47         name: queue
  48         doc: |
  49             The shaper is attached to the given device queue,
  50             the @id represents the queue number.
  51       -
  52         name: node
  53         doc: |
  54              The shaper allows grouping of queues or other
  55              node shapers; can be nested in either @netdev
  56              shapers or other @node shapers, allowing placement
  57              in any location of the scheduling tree, except
  58              leaves and root.
  59   -
  60     type: enum
  61     name: metric
  62     doc: Different metric supported by the shaper.
  63     entries:
  64       -
  65         name: bps
  66         doc: Shaper operates on a bits per second basis.
  67       -
  68         name: pps
  69         doc: Shaper operates on a packets per second basis.
  70
  71 attribute-sets:
  72   -
  73     name: net-shaper
  74     attributes:
  75       -
  76         name: handle
  77         type: nest
  78         nested-attributes: handle
  79         doc: Unique identifier for the given shaper inside the owning device.
  80       -
  81         name: metric
  82         type: u32
  83         enum: metric
  84         doc: Metric used by the given shaper for bw-min, bw-max and burst.
  85       -
  86         name: bw-min
  87         type: uint
  88         doc: Guaranteed bandwidth for the given shaper.
  89       -
  90         name: bw-max
  91         type: uint
  92         doc: Maximum bandwidth for the given shaper or 0 when unlimited.
  93       -
  94         name: burst
  95         type: uint
  96         doc: |
  97           Maximum burst-size for shaping. Should not be interpreted
  98           as a quantum.
  99       -
 100         name: priority
 101         type: u32
 102         doc: |
 103           Scheduling priority for the given shaper. The priority
 104           scheduling is applied to sibling shapers.
 105       -
 106         name: weight
 107         type: u32
 108         doc: |
 109           Relative weight for round robin scheduling of the
 110           given shaper.
 111           The scheduling is applied to all sibling shapers
 112           with the same priority.
 113       -
 114         name: ifindex
 115         type: u32
 116         doc: Interface index owning the specified shaper.
 117       -
 118         name: parent
 119         type: nest
 120         nested-attributes: handle
 121         doc: |
 122           Identifier for the parent of the affected shaper.
 123           Only needed for @group operation.
 124       -
 125         name: leaves
 126         type: nest
 127         multi-attr: true
 128         nested-attributes: leaf-info
 129         doc: |
 130            Describes a set of leaves shapers for a @group operation.
 131   -
 132     name: handle
 133     attributes:
 134       -
 135         name: scope
 136         type: u32
 137         enum: scope
 138         doc: Defines the shaper @id interpretation.
 139       -
 140         name: id
 141         type: u32
 142         doc: |
 143           Numeric identifier of a shaper. The id semantic depends on
 144           the scope. For @queue scope it's the queue id and for @node
 145           scope it's the node identifier.
 146   -
 147     name: leaf-info
 148     subset-of: net-shaper
 149     attributes:
 150       -
 151         name: handle
 152       -
 153         name: priority
 154       -
 155         name: weight
 156   -
 157     name: caps
 158     attributes:
 159       -
 160         name: ifindex
 161         type: u32
 162         doc: Interface index queried for shapers capabilities.
 163       -
 164         name: scope
 165         type: u32
 166         enum: scope
 167         doc: The scope to which the queried capabilities apply.
 168       -
 169         name: support-metric-bps
 170         type: flag
 171         doc: The device accepts 'bps' metric for bw-min, bw-max and burst.
 172       -
 173         name: support-metric-pps
 174         type: flag
 175         doc: The device accepts 'pps' metric for bw-min, bw-max and burst.
 176       -
 177         name: support-nesting
 178         type: flag
 179         doc: |
 180           The device supports nesting shaper belonging to this scope
 181           below 'node' scoped shapers. Only 'queue' and 'node'
 182           scope can have flag 'support-nesting'.
 183       -
 184         name: support-bw-min
 185         type: flag
 186         doc: The device supports a minimum guaranteed B/W.
 187       -
 188         name: support-bw-max
 189         type: flag
 190         doc: The device supports maximum B/W shaping.
 191       -
 192         name: support-burst
 193         type: flag
 194         doc: The device supports a maximum burst size.
 195       -
 196         name: support-priority
 197         type: flag
 198         doc: The device supports priority scheduling.
 199       -
 200         name: support-weight
 201         type: flag
 202         doc: The device supports weighted round robin scheduling.
 203
 204 operations:
 205   list:
 206     -
 207       name: get
 208       doc: |
 209         Get information about a shaper for a given device.
 210       attribute-set: net-shaper
 211
 212       do:
 213         pre: net-shaper-nl-pre-doit
 214         post: net-shaper-nl-post-doit
 215         request:
 216           attributes: &ns-binding
 217             - ifindex
 218             - handle
 219         reply:
 220           attributes: &ns-attrs
 221             - ifindex
 222             - parent
 223             - handle
 224             - metric
 225             - bw-min
 226             - bw-max
 227             - burst
 228             - priority
 229             - weight
 230
 231       dump:
 232         pre: net-shaper-nl-pre-dumpit
 233         post: net-shaper-nl-post-dumpit
 234         request:
 235           attributes:
 236             - ifindex
 237         reply:
 238           attributes: *ns-attrs
 239     -
 240       name: set
 241       doc: |
 242         Create or update the specified shaper.
 243         The set operation can't be used to create a @node scope shaper,
 244         use the @group operation instead.
 245       attribute-set: net-shaper
 246       flags: [ admin-perm ]
 247
 248       do:
 249         pre: net-shaper-nl-pre-doit
 250         post: net-shaper-nl-post-doit
 251         request:
 252           attributes:
 253             - ifindex
 254             - handle
 255             - metric
 256             - bw-min
 257             - bw-max
 258             - burst
 259             - priority
 260             - weight
 261
 262     -
 263       name: delete
 264       doc: |
 265         Clear (remove) the specified shaper. When deleting
 266         a @node shaper, reattach all the node's leaves to the
 267         deleted node's parent.
 268         If, after the removal, the parent shaper has no more
 269         leaves and the parent shaper scope is @node, the parent
 270         node is deleted, recursively.
 271         When deleting a @queue shaper or a @netdev shaper,
 272         the shaper disappears from the hierarchy, but the
 273         queue/device can still send traffic: it has an implicit
 274         node with infinite bandwidth. The queue's implicit node
 275         feeds an implicit RR node at the root of the hierarchy.
 276       attribute-set: net-shaper
 277       flags: [ admin-perm ]
 278
 279       do:
 280         pre: net-shaper-nl-pre-doit
 281         post: net-shaper-nl-post-doit
 282         request:
 283           attributes: *ns-binding
 284
 285     -
 286       name: group
 287       doc: |
 288         Create or update a scheduling group, attaching the specified
 289         @leaves shapers under the specified node identified by @handle.
 290         The @leaves shapers scope must be @queue and the node shaper
 291         scope must be either @node or @netdev.
 292         When the node shaper has @node scope, if the @handle @id is not
 293         specified, a new shaper of such scope is created, otherwise the
 294         specified node must already exist.
 295         When updating an existing node shaper, the specified @leaves are
 296         added to the existing node; such node will also retain any preexisting
 297         leave.
 298         The @parent handle for a new node shaper defaults to the parent
 299         of all the leaves, provided all the leaves share the same parent.
 300         Otherwise @parent handle must be specified.
 301         The user can optionally provide shaping attributes for the node
 302         shaper.
 303         The operation is atomic, on failure no change is applied to
 304         the device shaping configuration, otherwise the @node shaper
 305         full identifier, comprising @binding and @handle, is provided
 306         as the reply.
 307       attribute-set: net-shaper
 308       flags: [ admin-perm ]
 309
 310       do:
 311         pre: net-shaper-nl-pre-doit
 312         post: net-shaper-nl-post-doit
 313         request:
 314           attributes:
 315             - ifindex
 316             - parent
 317             - handle
 318             - metric
 319             - bw-min
 320             - bw-max
 321             - burst
 322             - priority
 323             - weight
 324             - leaves
 325         reply:
 326           attributes: *ns-binding
 327
 328     -
 329       name: cap-get
 330       doc: |
 331         Get the shaper capabilities supported by the given device
 332         for the specified scope.
 333       attribute-set: caps
 334
 335       do:
 336         pre: net-shaper-nl-cap-pre-doit
 337         post: net-shaper-nl-cap-post-doit
 338         request:
 339           attributes:
 340             - ifindex
 341             - scope
 342         reply:
 343           attributes: &cap-attrs
 344             - ifindex
 345             - scope
 346             - support-metric-bps
 347             - support-metric-pps
 348             - support-nesting
 349             - support-bw-min
 350             - support-bw-max
 351             - support-burst
 352             - support-priority
 353             - support-weight
 354
 355       dump:
 356         pre: net-shaper-nl-cap-pre-dumpit
 357         post: net-shaper-nl-cap-post-dumpit
 358         request:
 359           attributes:
 360             - ifindex
 361         reply:
 362           attributes: *cap-attrs