Document that quota and burst can be configured in either order, and that the configured burst is retained across quota changes while its runtime contribution is capped by the current quota.
Signed-off-by: Zhe Liu <[email protected]> --- Documentation/admin-guide/cgroup-v2.rst | 7 ++++++- Documentation/scheduler/sched-bwc.rst | 22 +++++++++++++--------- 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 86a2a0099178..e94285d48d0c 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1231,7 +1231,12 @@ will be referred to. All time durations are in microseconds. A read-write single value file which exists on non-root cgroups. The default is "0". - The burst in the range [0, $MAX]. + The burst in microseconds, with a lower bound of 0 and an upper bound + independent of the current quota. The configured value is retained + when the quota changes and may be larger than the current quota. + During CFS runtime refill, the burst contribution is capped at the + current quota. The quota and burst files can therefore be written + in either order. This file affects only processes under the fair-class scheduler and a BPF scheduler with the ``cgroup_set_bandwidth`` callback depending on what diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst index e881a945c188..19cd08195f6b 100644 --- a/Documentation/scheduler/sched-bwc.rst +++ b/Documentation/scheduler/sched-bwc.rst @@ -90,20 +90,22 @@ bandwidth restriction in place, such a group is described as an unconstrained bandwidth group. This represents the traditional work-conserving behavior for CFS. -Writing any (valid) positive value(s) no smaller than cpu.cfs_burst_us will -enact the specified bandwidth limit. The minimum quota allowed for the quota or -period is 1ms. There is also an upper bound on the period length of 1s. -Additional restrictions exist when bandwidth limits are used in a hierarchical -fashion, these are explained in more detail below. +Writing any valid positive quota value will enact the specified bandwidth +limit. The minimum quota allowed for the quota or period is 1ms. There is +also an upper bound on the period length of 1s. Additional restrictions +exist when bandwidth limits are used in a hierarchical fashion, these are +explained in more detail below. Writing any negative value to cpu.cfs_quota_us will remove the bandwidth limit and return the group to an unconstrained state once more. A value of 0 for cpu.cfs_burst_us indicates that the group can not accumulate any unused bandwidth. It makes the traditional bandwidth control behavior for -CFS unchanged. Writing any (valid) positive value(s) no larger than -cpu.cfs_quota_us into cpu.cfs_burst_us will enact the cap on unused bandwidth -accumulation. +CFS unchanged. A valid positive value written to cpu.cfs_burst_us is retained +when the quota changes. If it is larger than the current quota, the burst +contribution during runtime refill is capped at the current quota. + +The quota and burst files can be updated in either order. Any updates to a group's bandwidth specification will result in it becoming unthrottled if it is in a constrained state. @@ -243,4 +245,6 @@ Examples # echo 50000 > cpu.cfs_period_us /* period = 50ms */ # echo 10000 > cpu.cfs_burst_us /* burst = 10ms */ - Larger buffer setting (no larger than quota) allows greater burst capacity. + A larger buffer setting allows greater burst capacity. If the configured + burst is larger than the quota, the burst contribution is capped at the + quota during runtime refill. -- 2.25.1
