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 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 34definitions: 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 71attribute-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 204operations: 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 363