[PATCH] cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec

[PATCH] cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec

[Tao Cui]

From: Tao Cui <cuitao@kylinos.cn>

cgroup_base_stat_cputime_show() unconditionally prints a fourth base
stat, nice_usec, in addition to usage_usec/user_usec/system_usec, and
also prints core_sched.force_idle_usec when CONFIG_SCHED_CORE is enabled.
Neither field is currently described in the cpu.stat section of
cgroup-v2.rst, which still states it "always reports the following three
stats".

nice_usec was added by commit aefa398d93d5 ("cgroup/rstat: Tracking
cgroup-level niced CPU time") and core_sched.force_idle_usec by commit
1fcf54deb767 ("sched/core: add forced idle accounting for cgroups"); the
documentation was not updated in either case.

Update the cpu.stat description to list both fields and fix the count.

Signed-off-by: Tao Cui <cuitao@kylinos.cn>
---
 Documentation/admin-guide/cgroup-v2.rst | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 0df15a672cf3..778b759dd892 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1144,12 +1144,18 @@ will be referred to. All time durations are in microseconds.
 	A read-only flat-keyed file.
 	This file exists whether the controller is enabled or not.
 
-	It always reports the following three stats, which account for all the
+	It always reports the following four stats, which account for all the
 	processes in the cgroup (including those in descendant cgroups):
 
 	- usage_usec
 	- user_usec
 	- system_usec
+	- nice_usec
+
+	When core scheduling (CONFIG_SCHED_CORE) is enabled, an additional
+	stat is reported:
+
+	- core_sched.force_idle_usec
 
 	and the following five when the controller is enabled, which account for
 	only the processes under the fair-class scheduler:
-- 
2.43.0

Re: [PATCH] cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec

[Joshua Hahn]

> From: Tao Cui <cuitao@kylinos.cn>
> 
> cgroup_base_stat_cputime_show() unconditionally prints a fourth base
> stat, nice_usec, in addition to usage_usec/user_usec/system_usec, and
> also prints core_sched.force_idle_usec when CONFIG_SCHED_CORE is enabled.
> Neither field is currently described in the cpu.stat section of
> cgroup-v2.rst, which still states it "always reports the following three
> stats".
> 
> nice_usec was added by commit aefa398d93d5 ("cgroup/rstat: Tracking
> cgroup-level niced CPU time") and core_sched.force_idle_usec by commit
> 1fcf54deb767 ("sched/core: add forced idle accounting for cgroups"); the
> documentation was not updated in either case.
> 
> Update the cpu.stat description to list both fields and fix the count.
> 
> Signed-off-by: Tao Cui <cuitao@kylinos.cn>

Hello Tao, thank you for the patch! I should have updated this when
I added the nice stats. Thank you for finding this and updating it.

> ---
>  Documentation/admin-guide/cgroup-v2.rst | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
> index 0df15a672cf3..778b759dd892 100644
> --- a/Documentation/admin-guide/cgroup-v2.rst
> +++ b/Documentation/admin-guide/cgroup-v2.rst
> @@ -1144,12 +1144,18 @@ will be referred to. All time durations are in microseconds.
>  	A read-only flat-keyed file.
>  	This file exists whether the controller is enabled or not.
>  
> -	It always reports the following three stats, which account for all the
> +	It always reports the following four stats, which account for all the
>  	processes in the cgroup (including those in descendant cgroups):

I have to ask, which tree is this based on? I can't seem to find a single
tree that contains the "(including those in descendant cgroups)" section
anywhere. 

>  	- usage_usec
>  	- user_usec
>  	- system_usec
> +	- nice_usec
> +
> +	When core scheduling (CONFIG_SCHED_CORE) is enabled, an additional
> +	stat is reported:
> +
> +	- core_sched.force_idle_usec
>  
>  	and the following five when the controller is enabled, which account for
>  	only the processes under the fair-class scheduler:
> -- 
> 2.43.0

Otherwise, the change looks good. I just wanted to know what it was based
on, in case I'm missing something. Thanks, have a great day!
Joshua

Re: [PATCH] cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec

[Michal Koutný]

[-- Attachment #1: Type: text/plain, Size: 471 bytes --]

On Mon, Jul 20, 2026 at 08:02:26AM -0700, Joshua Hahn <joshua.hahnjy@gmail.com> wrote:
> I have to ask, which tree is this based on? I can't seem to find a single
> tree that contains the "(including those in descendant cgroups)" section
> anywhere. 

It is most likely linux-next which contains a nearby modification from
[1] (or it was based on that regardless).

HTH,
Michal

[1] https://lore.kernel.org/lkml/20260629060636.200118-1-sunshaojie@kylinos.cn/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 265 bytes --]

Re: [PATCH] cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec

[Michal Koutný]

[-- Attachment #1: Type: text/plain, Size: 727 bytes --]

On Sat, Jul 18, 2026 at 04:01:00PM +0800, Tao Cui <cui.tao@linux.dev> wrote:
> From: Tao Cui <cuitao@kylinos.cn>
> 
> cgroup_base_stat_cputime_show() unconditionally prints a fourth base
> stat, nice_usec, in addition to usage_usec/user_usec/system_usec, and
> also prints core_sched.force_idle_usec when CONFIG_SCHED_CORE is enabled.
> Neither field is currently described in the cpu.stat section of
> cgroup-v2.rst, which still states it "always reports the following three
> stats".

Just to better sense popularity of the fields -- have you found this out
by:
a) reading cpu.stat and being confused about semantics of the fields or
b) scanning files/code vs docs looking for discrepancies?

Thanks,
Michal

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 265 bytes --]

Re: [PATCH] cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec

[Joshua Hahn]

> On Mon, Jul 20, 2026 at 08:02:26AM -0700, Joshua Hahn <joshua.hahnjy@gmail.com> wrote:
> > I have to ask, which tree is this based on? I can't seem to find a single
> > tree that contains the "(including those in descendant cgroups)" section
> > anywhere. 
> 
> It is most likely linux-next which contains a nearby modification from
> [1] (or it was based on that regardless).

Hello Michal,

Thank you, I must have missed linux-next in my searching... that makes
a lot of sense! With that, Tao, please feel free to add my review tag:

Reviewed-by: Joshua Hahn <joshua.hahnjy@gmail.com>

Thanks, have a great day!
Joshua

> HTH,
> Michal
> 
> [1] https://lore.kernel.org/lkml/20260629060636.200118-1-sunshaojie@kylinos.cn/

Re: [PATCH] cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec

[Tao Cui]

在 2026/7/20 23:27, Joshua Hahn 写道:
>> On Mon, Jul 20, 2026 at 08:02:26AM -0700, Joshua Hahn <joshua.hahnjy@gmail.com> wrote:
>>> I have to ask, which tree is this based on? I can't seem to find a single
>>> tree that contains the "(including those in descendant cgroups)" section
>>> anywhere. 
>>
>> It is most likely linux-next which contains a nearby modification from
>> [1] (or it was based on that regardless).
> 
> Hello Michal,
> 
> Thank you, I must have missed linux-next in my searching... that makes
> a lot of sense! With that, Tao, please feel free to add my review tag:
> 
> Reviewed-by: Joshua Hahn <joshua.hahnjy@gmail.com>
> 
Thanks Michal for the pointer, and Joshua for the tag.
Based on linux-next (next-20260717).

Thanks，
Tao
> Thanks, have a great day!
> Joshua
> 
>> HTH,
>> Michal
>>
>> [1] https://lore.kernel.org/lkml/20260629060636.200118-1-sunshaojie@kylinos.cn/

Re: [PATCH] cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec

[Tao Cui]

在 2026/7/20 23:26, Michal Koutný 写道:
> On Sat, Jul 18, 2026 at 04:01:00PM +0800, Tao Cui <cui.tao@linux.dev> wrote:
>> From: Tao Cui <cuitao@kylinos.cn>
>>
>> cgroup_base_stat_cputime_show() unconditionally prints a fourth base
>> stat, nice_usec, in addition to usage_usec/user_usec/system_usec, and
>> also prints core_sched.force_idle_usec when CONFIG_SCHED_CORE is enabled.
>> Neither field is currently described in the cpu.stat section of
>> cgroup-v2.rst, which still states it "always reports the following three
>> stats".
> 
> Just to better sense popularity of the fields -- have you found this out
> by:
> a) reading cpu.stat and being confused about semantics of the fields or
> b) scanning files/code vs docs looking for discrepancies?
> 
(b). I found it while auditing the cgroup cpu controller, comparing
what cgroup_base_stat_cputime_show() prints against the cpu.stat docs.
nice_usec is emitted unconditionally but not listed there, and the
"three stats" count was stale.

The audit is groundwork for a prototype daemon that monitors
per-cgroup resource usage and adjusts limits dynamically. The design
is inspired by DAMON, but DAMON targets a single resource domain,
whereas container workloads need coordinated control across several
(cpu, memory, io) — which is why I'm going through the per-controller
stat interfaces.

Thanks,
Tao
> Thanks,
> Michal