[PATCH v3 0/3] sched/fair: remove quota/burst write-order dependency

[PATCH v3 0/3] sched/fair: remove quota/burst write-order dependency

[Zhe Liu]

The CPU bandwidth quota and burst controls currently make the order of
userspace writes significant. A burst configured while quota is unlimited
can prevent a later finite quota from being installed, and updating the
burst before increasing the quota can fail with -EINVAL.

Remove the write-order dependency by decoupling burst validation from the
current quota. The previous quota-relative checks implicitly limited the
maximum configurable burst to max_bw_runtime_us / 2 for a finite quota,
so retain that limit as an independent upper bound.

Keep the configured burst unchanged across quota updates, and cap the
burst actually available at refill time to min(burst, quota). This allows
cpu.max and cpu.max.burst to be updated in either order without changing
the maximum burst previously allowed for a finite quota.

The series also adds a selftest covering both write orders and documents
the resulting behavior for cgroup v1 and cgroup v2.

---
Changes in v3:
- Use max_bw_runtime_us / 2 as an independent upper bound for burst,
  preserving the maximum burst previously allowed with a finite quota
  while removing its dependency on the current quota.
- Drop Cc: stable@vger.kernel.org from patch 1.
- Update the cpu.max.burst documentation to describe the configured burst
  independently of the current quota and the quota-relative clamp applied
  at runtime refill.

Changes in v2:
- Keep the configured burst independent of quota changes instead of
  adjusting or resetting it when the quota is updated.
- Move the quota-relative restriction to the CFS runtime refill path,
  where the effective burst is capped to the current quota.
- Add selftests covering quota and burst updates in both write orders and
  document the resulting behavior for cgroup v1 and cgroup v2.

v2: https://lore.kernel.org/all/20260904062013.504236-1-liuzhe1@kylinos.cn/
v1: https://lore.kernel.org/all/20260820033218.214259-1-liuzhe1@kylinos.cn/

Zhe Liu (3):
  sched/fair: remove quota/burst write-order dependency
  selftests: cgroup: test CPU quota and burst write order
  docs: cgroup-v2: document CPU quota and burst ordering

 Documentation/admin-guide/cgroup-v2.rst   |  7 +++-
 Documentation/scheduler/sched-bwc.rst     | 22 ++++++++-----
 kernel/sched/core.c                       |  3 +-
 kernel/sched/fair.c                       |  3 +-
 tools/testing/selftests/cgroup/test_cpu.c | 40 +++++++++++++++++++++++
 5 files changed, 62 insertions(+), 13 deletions(-)


base-commit: df2908090cda368b01ff43709f51890076c56157
-- 
2.25.1

[PATCH v3 1/3] sched/fair: remove quota/burst write-order dependency

[Zhe Liu]

Burst validation currently depends on the active quota, so the same quota
and burst values may be accepted or rejected depending on the order in
which userspace updates them.

Make burst validation independent of the current quota while preserving,
for finite quotas, the previous maximum configurable burst at
max_bw_runtime_us / 2. Keep the configured burst across quota updates and
cap the effective burst to min(burst, quota) when CFS runtime is refilled.

Fixes: f4183717b370 ("sched/fair: Introduce the burstable CFS controller")
Signed-off-by: Zhe Liu <liuzhe1@kylinos.cn>
Tested-by: Tao Cui <cuitao@kylinos.cn>
Reviewed-by: Michal Koutný <mkoutny@suse.com>
---
 kernel/sched/core.c | 3 +--
 kernel/sched/fair.c | 3 ++-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/kernel/sched/core.c b/kernel/sched/core.c
index b998ef6b87af..c399f0a59c25 100644
--- a/kernel/sched/core.c
+++ b/kernel/sched/core.c
@@ -10181,8 +10181,7 @@ static int tg_set_bandwidth(struct task_group *tg,
 	if (quota_us != RUNTIME_INF && quota_us > max_bw_runtime_us)
 		return -EINVAL;
 
-	if (quota_us != RUNTIME_INF && (burst_us > quota_us ||
-					burst_us + quota_us > max_bw_runtime_us))
+	if (burst_us > max_bw_runtime_us / 2)
 		return -EINVAL;
 
 #ifdef CONFIG_CFS_BANDWIDTH
diff --git a/kernel/sched/fair.c b/kernel/sched/fair.c
index ade1eceb39b8..e6f9d9296fd2 100644
--- a/kernel/sched/fair.c
+++ b/kernel/sched/fair.c
@@ -6627,7 +6627,8 @@ void __refill_cfs_bandwidth_runtime(struct cfs_bandwidth *cfs_b)
 		cfs_b->nr_burst++;
 	}
 
-	cfs_b->runtime = min(cfs_b->runtime, cfs_b->quota + cfs_b->burst);
+	cfs_b->runtime = min(cfs_b->runtime,
+			     cfs_b->quota + min(cfs_b->burst, cfs_b->quota));
 	cfs_b->runtime_snap = cfs_b->runtime;
 }
 
-- 
2.25.1

[PATCH v3 2/3] selftests: cgroup: test CPU quota and burst write order

[Zhe Liu]

Add regression coverage for the quota and burst write-order dependency.
Verify that a burst configured with an unlimited quota is retained when
switching to a finite quota, and that quota and burst can be updated in
either order without changing the configured burst.

Signed-off-by: Zhe Liu <liuzhe1@kylinos.cn>
---
 tools/testing/selftests/cgroup/test_cpu.c | 40 +++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/tools/testing/selftests/cgroup/test_cpu.c b/tools/testing/selftests/cgroup/test_cpu.c
index 735a53bb222b..243fc979a3e8 100644
--- a/tools/testing/selftests/cgroup/test_cpu.c
+++ b/tools/testing/selftests/cgroup/test_cpu.c
@@ -733,6 +733,45 @@ static int test_cpucg_max(const char *root)
 	return ret;
 }
 
+static int test_cpucg_max_burst(const char *root)
+{
+	int ret = KSFT_FAIL;
+	char *cpucg;
+
+	cpucg = cg_name(root, "cpucg_max_burst");
+	if (!cpucg)
+		return KSFT_FAIL;
+
+	if (cg_create(cpucg))
+		goto cleanup;
+
+	if (cg_write(cpucg, "cpu.max", "max 100000") ||
+	    cg_write(cpucg, "cpu.max.burst", "100000000") ||
+	    cg_write(cpucg, "cpu.max", "50000 100000") ||
+	    cg_read_strcmp(cpucg, "cpu.max.burst", "100000000\n"))
+		goto cleanup;
+
+	if (cg_write(cpucg, "cpu.max.burst", "80000") ||
+	    cg_write(cpucg, "cpu.max", "100000 100000") ||
+	    cg_read_strcmp(cpucg, "cpu.max.burst", "80000\n"))
+		goto cleanup;
+
+	if (cg_write(cpucg, "cpu.max.burst", "0") ||
+	    cg_write(cpucg, "cpu.max", "50000 100000") ||
+	    cg_write(cpucg, "cpu.max", "100000 100000") ||
+	    cg_write(cpucg, "cpu.max.burst", "80000") ||
+	    cg_read_strcmp(cpucg, "cpu.max.burst", "80000\n"))
+		goto cleanup;
+
+	ret = KSFT_PASS;
+
+cleanup:
+	cg_destroy(cpucg);
+	free(cpucg);
+
+	return ret;
+}
+
 /*
  * This test verifies that a process inside of a nested cgroup whose parent
  * group has a cpu.max value set, is properly throttled.
@@ -822,6 +861,7 @@ struct cpucg_test {
 	T(test_cpucg_nested_weight_overprovisioned),
 	T(test_cpucg_nested_weight_underprovisioned),
 	T(test_cpucg_max),
+	T(test_cpucg_max_burst),
 	T(test_cpucg_max_nested),
 };
 #undef T
-- 
2.25.1

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

[Zhe Liu]

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