[PATCH][RESEND] cgroup, docs: document the root cgroup behavior of cpu and io controllers

[PATCH][RESEND] cgroup, docs: document the root cgroup behavior of cpu and io controllers

[Maciej S. Szmigiero]

Currently, cgroups v2 documentation contains only a generic remark that
"How resource consumption in the root cgroup is governed is up to each
controller", which isn't really telling users much, who need to dig in the
code and / or commit messages to learn the exact behavior.

In cgroups v1 at least the blkio controller had its operation with respect
to competition between child threads and child cgroups documented in
blkio-controller.txt, with references to cfq-iosched.txt.
Also, cgroups v2 documentation describes v1 behavior of both cpu and
blkio controllers in an "Issues with v1" section.

Let's document this behavior also for cgroups v2 to make life easier for
users.

Signed-off-by: Maciej S. Szmigiero <mail@maciej.szmigiero.name>
---
This is a resend without any changes.

 Documentation/cgroup-v2.txt | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt
index c783bbb9d0fb..f8824c288dbb 100644
--- a/Documentation/cgroup-v2.txt
+++ b/Documentation/cgroup-v2.txt
@@ -906,6 +906,13 @@ have placed RT processes into nonroot cgroups during the system boot
 process, and these processes may need to be moved to the root cgroup
 before the cpu controller can be enabled.
 
+When distributing CPU cycles in the root cgroup each thread in this
+cgroup is treated as if it was hosted in a separate child cgroup of the
+root cgroup. This child cgroup weight is dependent on its thread nice
+level.
+For details of this mapping see sched_prio_to_weight array in
+kernel/sched/core.c file (values from this array should be scaled
+appropriately so the neutral - nice 0 - value is 100 instead of 1024).
 
 CPU Interface Files
 ~~~~~~~~~~~~~~~~~~~
@@ -1247,6 +1254,10 @@ limit distribution; however, weight based distribution is available
 only if cfq-iosched is in use and neither scheme is available for
 blk-mq devices.
 
+Root cgroup processes are hosted in an implicit leaf child node.
+When distributing IO resources this implicit child node is taken into
+account as if it was a normal child cgroup of the root cgroup with a
+weight value of 200.
 
 IO Interface Files
 ~~~~~~~~~~~~~~~~~~

Re: [PATCH][RESEND] cgroup, docs: document the root cgroup behavior of cpu and io controllers

[Tejun Heo]

Hello,

On Thu, Jan 04, 2018 at 10:57:00PM +0100, Maciej S. Szmigiero wrote:
> Currently, cgroups v2 documentation contains only a generic remark that
> "How resource consumption in the root cgroup is governed is up to each
> controller", which isn't really telling users much, who need to dig in the
> code and / or commit messages to learn the exact behavior.

I don't think we want to fully guarantee the current behavior.  On the
scheduler side, I don't think it's likely to change but blkio side
*might* change.  Can you please collect the root behavior in a separte
section and clearly note that the behaviors are subject to change?

Thanks.

-- 
tejun

Re: [PATCH][RESEND] cgroup, docs: document the root cgroup behavior of cpu and io controllers

[Maciej S. Szmigiero]

Hello,

On 08.01.2018 13:15, Tejun Heo wrote:
> Hello,
> 
> On Thu, Jan 04, 2018 at 10:57:00PM +0100, Maciej S. Szmigiero wrote:
>> Currently, cgroups v2 documentation contains only a generic remark that
>> "How resource consumption in the root cgroup is governed is up to each
>> controller", which isn't really telling users much, who need to dig in the
>> code and / or commit messages to learn the exact behavior.
> 
> I don't think we want to fully guarantee the current behavior.  On the
> scheduler side, I don't think it's likely to change but blkio side
> *might* change.  Can you please collect the root behavior in a separte
> section and clearly note that the behaviors are subject to change?

Will do.

> Thanks.
> 

Maciej