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