[PATCH v3 3/3] docs: cgroup-v2: document CPU quota and burst ordering

[Zhe Liu <liuzhe1@kylinos.cn>]

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 <liuzhe1@kylinos.cn>
---
 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