[PATCH v2 3/3] Documentation: describe CPU quota and burst ordering

[Zhe Liu]

Document the independent quota and burst configuration and the runtime
burst clamp.

Signed-off-by: Zhe Liu <liuzhe1@xxxxxxxxxx>
---
 Documentation/admin-guide/cgroup-v2.rst |  5 ++++-
 Documentation/scheduler/sched-bwc.rst   | 21 ++++++++++++---------
 2 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 7c2a8ed80071..57253c2c1819 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1229,7 +1229,10 @@ 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 the range [0, $MAX]. The configured value is retained when
+	the quota changes and may be larger than the current quota. During CFS
+	runtime refill, the effective burst is limited to 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.
 
diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
index e881a945c188..08a54ee84da2 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 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, CFS limits the
+effective burst during runtime refill to 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,5 @@ 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 effective burst is limited to the quota.
-- 
2.25.1