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