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