1# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) 2name: net-shaper 3 4doc: | 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 29definitions: 30 - 31 type: enum 32 name: scope 33 doc: Defines the shaper @id interpretation. 34 render-max: true 35 entries: 36 - name: unspec 37 doc: The scope is not specified. 38 - 39 name: netdev 40 doc: The main shaper for the given network device. 41 - 42 name: queue 43 doc: | 44 The shaper is attached to the given device queue, 45 the @id represents the queue number. 46 - 47 name: node 48 doc: | 49 The shaper allows grouping of queues or other 50 node shapers; can be nested in either @netdev 51 shapers or other @node shapers, allowing placement 52 in any location of the scheduling tree, except 53 leaves and root. 54 - 55 type: enum 56 name: metric 57 doc: Different metric supported by the shaper. 58 entries: 59 - 60 name: bps 61 doc: Shaper operates on a bits per second basis. 62 - 63 name: pps 64 doc: Shaper operates on a packets per second basis. 65 66attribute-sets: 67 - 68 name: net-shaper 69 attributes: 70 - 71 name: handle 72 type: nest 73 nested-attributes: handle 74 doc: Unique identifier for the given shaper inside the owning device. 75 - 76 name: metric 77 type: u32 78 enum: metric 79 doc: Metric used by the given shaper for bw-min, bw-max and burst. 80 - 81 name: bw-min 82 type: uint 83 doc: Guaranteed bandwidth for the given shaper. 84 - 85 name: bw-max 86 type: uint 87 doc: Maximum bandwidth for the given shaper or 0 when unlimited. 88 - 89 name: burst 90 type: uint 91 doc: | 92 Maximum burst-size for shaping. Should not be interpreted 93 as a quantum. 94 - 95 name: priority 96 type: u32 97 doc: | 98 Scheduling priority for the given shaper. The priority 99 scheduling is applied to sibling shapers. 100 - 101 name: weight 102 type: u32 103 doc: | 104 Relative weight for round robin scheduling of the 105 given shaper. 106 The scheduling is applied to all sibling shapers 107 with the same priority. 108 - 109 name: ifindex 110 type: u32 111 doc: Interface index owning the specified shaper. 112 - 113 name: parent 114 type: nest 115 nested-attributes: handle 116 doc: | 117 Identifier for the parent of the affected shaper. 118 Only needed for @group operation. 119 - 120 name: leaves 121 type: nest 122 multi-attr: true 123 nested-attributes: leaf-info 124 doc: | 125 Describes a set of leaves shapers for a @group operation. 126 - 127 name: handle 128 attributes: 129 - 130 name: scope 131 type: u32 132 enum: scope 133 doc: Defines the shaper @id interpretation. 134 - 135 name: id 136 type: u32 137 doc: | 138 Numeric identifier of a shaper. The id semantic depends on 139 the scope. For @queue scope it's the queue id and for @node 140 scope it's the node identifier. 141 - 142 name: leaf-info 143 subset-of: net-shaper 144 attributes: 145 - 146 name: handle 147 - 148 name: priority 149 - 150 name: weight 151 152operations: 153 list: 154 - 155 name: get 156 doc: | 157 Get information about a shaper for a given device. 158 attribute-set: net-shaper 159 160 do: 161 pre: net-shaper-nl-pre-doit 162 post: net-shaper-nl-post-doit 163 request: 164 attributes: &ns-binding 165 - ifindex 166 - handle 167 reply: 168 attributes: &ns-attrs 169 - ifindex 170 - parent 171 - handle 172 - metric 173 - bw-min 174 - bw-max 175 - burst 176 - priority 177 - weight 178 179 dump: 180 pre: net-shaper-nl-pre-dumpit 181 post: net-shaper-nl-post-dumpit 182 request: 183 attributes: 184 - ifindex 185 reply: 186 attributes: *ns-attrs 187 - 188 name: set 189 doc: | 190 Create or update the specified shaper. 191 The set operation can't be used to create a @node scope shaper, 192 use the @group operation instead. 193 attribute-set: net-shaper 194 flags: [ admin-perm ] 195 196 do: 197 pre: net-shaper-nl-pre-doit 198 post: net-shaper-nl-post-doit 199 request: 200 attributes: 201 - ifindex 202 - handle 203 - metric 204 - bw-min 205 - bw-max 206 - burst 207 - priority 208 - weight 209 210 - 211 name: delete 212 doc: | 213 Clear (remove) the specified shaper. When deleting 214 a @node shaper, reattach all the node's leaves to the 215 deleted node's parent. 216 If, after the removal, the parent shaper has no more 217 leaves and the parent shaper scope is @node, the parent 218 node is deleted, recursively. 219 When deleting a @queue shaper or a @netdev shaper, 220 the shaper disappears from the hierarchy, but the 221 queue/device can still send traffic: it has an implicit 222 node with infinite bandwidth. The queue's implicit node 223 feeds an implicit RR node at the root of the hierarchy. 224 attribute-set: net-shaper 225 flags: [ admin-perm ] 226 227 do: 228 pre: net-shaper-nl-pre-doit 229 post: net-shaper-nl-post-doit 230 request: 231 attributes: *ns-binding 232 233 - 234 name: group 235 doc: | 236 Create or update a scheduling group, attaching the specified 237 @leaves shapers under the specified node identified by @handle. 238 The @leaves shapers scope must be @queue and the node shaper 239 scope must be either @node or @netdev. 240 When the node shaper has @node scope, if the @handle @id is not 241 specified, a new shaper of such scope is created, otherwise the 242 specified node must already exist. 243 When updating an existing node shaper, the specified @leaves are 244 added to the existing node; such node will also retain any preexisting 245 leave. 246 The @parent handle for a new node shaper defaults to the parent 247 of all the leaves, provided all the leaves share the same parent. 248 Otherwise @parent handle must be specified. 249 The user can optionally provide shaping attributes for the node 250 shaper. 251 The operation is atomic, on failure no change is applied to 252 the device shaping configuration, otherwise the @node shaper 253 full identifier, comprising @binding and @handle, is provided 254 as the reply. 255 attribute-set: net-shaper 256 flags: [ admin-perm ] 257 258 do: 259 pre: net-shaper-nl-pre-doit 260 post: net-shaper-nl-post-doit 261 request: 262 attributes: 263 - ifindex 264 - parent 265 - handle 266 - metric 267 - bw-min 268 - bw-max 269 - burst 270 - priority 271 - weight 272 - leaves 273 reply: 274 attributes: *ns-binding 275