tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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-write
251 post: net-shaper-nl-post-doit-write
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-write
282 post: net-shaper-nl-post-doit-write
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-write
313 post: net-shaper-nl-post-doit-write
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