summaryrefslogtreecommitdiff
path: root/Documentation/netlink/specs/net_shaper.yaml
blob: 8ebad0d02904f91c3c17670d15a51443c22ef301 (plain)
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