[PATCH] tools/sched_ext: scx_flatcg: Document cgroup v2 requirement

[PATCH] tools/sched_ext: scx_flatcg: Document cgroup v2 requirement

[luoliang]

From: Liang Luo <luoliang@kylinos.cn>

The BPF program relies on cgroup v2-specific features - specifically
BPF_MAP_TYPE_CGRP_STORAGE and cgroup v2 kfuncs (bpf_cgroup_ancestor,
bpf_cgroup_from_id, scx_bpf_task_cgroup, ...), none of which are
available on cgroup v1. The current file header describes the
algorithm but does not make this runtime requirement explicit, so
users running on a cgroup v1-only system get a confusing BPF load
error with no clear pointer to the cause.

Document the requirement in a Note paragraph at the end of the file
header so that it is visible to anyone reading the source.

No functional change.

Signed-off-by: Liang Luo <luoliang@kylinos.cn>
---
 tools/sched_ext/scx_flatcg.bpf.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/tools/sched_ext/scx_flatcg.bpf.c b/tools/sched_ext/scx_flatcg.bpf.c
index fec359581826..067e1a7991d4 100644
--- a/tools/sched_ext/scx_flatcg.bpf.c
+++ b/tools/sched_ext/scx_flatcg.bpf.c
@@ -42,6 +42,9 @@
  * The scheduler first picks the cgroup to run and then schedule the tasks
  * within by using nested weighted vtime scheduling by default. The
  * cgroup-internal scheduling can be switched to FIFO with the -f option.
+ *
+ * Note: Requires cgroup v2 (uses BPF_MAP_TYPE_CGRP_STORAGE and cgroup v2
+ * BPF kfuncs, neither of which are available on cgroup v1).
  */
 #include <scx/common.bpf.h>
 #include "scx_flatcg.h"
-- 
2.25.1

Re: [PATCH] tools/sched_ext: scx_flatcg: Document cgroup v2 requirement

[Tejun Heo]

On Wed, Jun 03, 2026 at 05:01:06PM +0800, Liang Luo wrote:
> The BPF program relies on cgroup v2-specific features - specifically
> BPF_MAP_TYPE_CGRP_STORAGE and cgroup v2 kfuncs (bpf_cgroup_ancestor,
> bpf_cgroup_from_id, scx_bpf_task_cgroup, ...), none of which are
> available on cgroup v1. The current file header describes the
> algorithm but does not make this runtime requirement explicit, so
> users running on a cgroup v1-only system get a confusing BPF load
> error with no clear pointer to the cause.

This doesn't look accurate on current kernels. BPF_MAP_TYPE_CGRP_STORAGE is
registered unconditionally and its fd access goes through
cgroup_v1v2_get_from_fd(), and bpf_cgroup_ancestor(), bpf_cgroup_from_id()
and scx_bpf_task_cgroup() all take a plain struct cgroup with no v1/v2
gating. The program should load fine on cgroup1.

Did you actually hit a load failure, and on which kernel? cgrp_storage's
cgroup1 access was only enabled in v6.8 by 73d9eb340d2b ("bpf: Enable
bpf_cgrp_storage for cgroup1 non-attach case"). Before that it was cgroup2
only, which would explain a failure on an older kernel.

Thanks.

--
tejun

Re: [PATCH] tools/sched_ext: scx_flatcg: Document cgroup v2 requirement

[luoliang]

On Wed, Jun 03, 2026 at 10:29:10PM -1000, Tejun Heo wrote:
> This doesn't look accurate on current kernels. BPF_MAP_TYPE_CGRP_STORAGE is
> registered unconditionally and its fd access goes through
> cgroup_v1v2_get_from_fd(), and bpf_cgroup_ancestor(), bpf_cgroup_from_id()
> and scx_bpf_task_cgroup() all take a plain struct cgroup with no v1/v2
> gating. The program should load fine on cgroup1.

You are right, thank you for the correction. I was wrong about the
v2 dependency.

> Did you actually hit a load failure, and on which kernel? cgrp_storage's
> cgroup1 access was only enabled in v6.8 by 73d9eb340d2b ("bpf: Enable
> bpf_cgrp_storage for cgroup1 non-attach case"). Before that it was cgroup2
> only, which would explain a failure on an older kernel.

I did observe a load failure on v7.1-rc3 with cgroup v1 at the time,
but I can no longer reproduce it now. It was likely caused by a local
misconfiguration or build environment issue rather than a genuine v2
dependency. I should have validated the root cause before submitting.
My apologies.

Please drop this patch.