docs: cgroup nits and fixes
Subsystems (2)
cover docs: cgroup nits and fixes
These are mostly formatting fixes for a few cases where html looks plain wrong, plus a couple of added cross-references, and a typo.
All issues spotted while reading cgroup docs. Results are checked manually for both html and pdf, using both Sphinx 2.4.4 and 3.2.1 for rendering.
All commits are against docs-next@52042e2db
Kir Kolyshkin (10):
docs/scheduler/sched-bwc: formatting fix docs/scheduler/sched-design-CFS: formatting fix docs/scheduler/sched-bwc: fix note rendering docs/scheduler/sched-bwc: add proper ref docs/scheduler/sched-bwc: note/link cgroup v2 docs/admin-guide: cgroup-v2: typos and spaces docs/admin-guide: cgroup-v2: fix cgroup.type rendering doc/admin-guide/cgroup-v2: use tables docs/admin-guide/cgroup-v2: nit docs/admin-guide/cgroup-v2: fix mount opt rendering
Documentation/admin-guide/cgroup-v2.rst | 60 +++++++++++--------- Documentation/scheduler/sched-bwc.rst | 18 ++++-- Documentation/scheduler/sched-design-CFS.rst | 6 +- Documentation/scheduler/sched-rt-group.rst | 2 + 4 files changed, 50 insertions(+), 36 deletions(-)
Signature · 1 line
2.29.2
PATCH 1/10 docs/scheduler/sched-bwc: formatting fix
In reply to a message not in the archiveSince commit d6a3b247627a3 these three lines are merged into one by the RST processor, making it hard to read. Use bullet points to separate the entries, like it's done in other similar places.
--- Documentation/scheduler/sched-bwc.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/scheduler/sched-bwc.rst +4 -3
@@ -25,9 +25,10 @@ Management ---------- Quota and period are managed within the cpu subsystem via cgroupfs. -cpu.cfs_quota_us: the total available run-time within a period (in microseconds) -cpu.cfs_period_us: the length of a period (in microseconds) -cpu.stat: exports throttling statistics [explained further below] +- cpu.cfs_quota_us: the total available run-time within a period (in + microseconds) +- cpu.cfs_period_us: the length of a period (in microseconds) +- cpu.stat: exports throttling statistics [explained further below] The default values are::
Signature · 1 line
2.29.2
PATCH 2/10 docs/scheduler/sched-design-CFS: formatting fix
In reply to Kir KolyshkinFix the rendering of the paragraph. Before the fix, the first line is rendered in bold (I'm not quite sure why) and is also separated from the rest of the paragraph, which is rendered with an indent.
--- Documentation/scheduler/sched-design-CFS.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/scheduler/sched-design-CFS.rst +3 -3
@@ -34,9 +34,9 @@ In CFS the virtual runtime is expressed and tracked via the per-task p->se.vruntime (nanosec-unit) value. This way, it's possible to accurately timestamp and measure the "expected CPU time" a task should have gotten. -[ small detail: on "ideal" hardware, at any time all tasks would have the same - p->se.vruntime value --- i.e., tasks would execute simultaneously and no task - would ever get "out of balance" from the "ideal" share of CPU time. ] + Small detail: on "ideal" hardware, at any time all tasks would have the same + p->se.vruntime value --- i.e., tasks would execute simultaneously and no task + would ever get "out of balance" from the "ideal" share of CPU time. CFS's task picking logic is based on this p->se.vruntime value and it is thus very simple: it always tries to run the task with the smallest p->se.vruntime
Signature · 1 line
2.29.2
PATCH 3/10 docs/scheduler/sched-bwc: fix note rendering
In reply to Kir Kolyshkin--- Documentation/scheduler/sched-bwc.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/scheduler/sched-bwc.rst +3 -2
@@ -2,8 +2,9 @@ CFS Bandwidth Control ===================== -[ This document only discusses CPU bandwidth control for SCHED_NORMAL. - The SCHED_RT case is covered in Documentation/scheduler/sched-rt-group.rst ] +.. note:: + This document only discusses CPU bandwidth control for SCHED_NORMAL. + The SCHED_RT case is covered in Documentation/scheduler/sched-rt-group.rst CFS bandwidth control is a CONFIG_FAIR_GROUP_SCHED extension which allows the specification of the maximum CPU bandwidth available to a group or hierarchy.
Signature · 1 line
2.29.2
PATCH 4/10 docs/scheduler/sched-bwc: add proper ref
In reply to a message not in the archiveAdd a proper reference instead of just using the file name.
--- Documentation/scheduler/sched-bwc.rst | 3 ++- Documentation/scheduler/sched-rt-group.rst | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-)
Documentation/scheduler/sched-bwc.rst +2 -1
@@ -4,7 +4,8 @@ CFS Bandwidth Control .. note:: This document only discusses CPU bandwidth control for SCHED_NORMAL. - The SCHED_RT case is covered in Documentation/scheduler/sched-rt-group.rst + The SCHED_RT case is covered in + :ref:`Documentation/scheduler/sched-rt-group.rst <sched-rt-group>`. CFS bandwidth control is a CONFIG_FAIR_GROUP_SCHED extension which allows the specification of the maximum CPU bandwidth available to a group or hierarchy.
Documentation/scheduler/sched-rt-group.rst +2 -0
@@ -1,3 +1,5 @@ +.. _sched-rt-group: + ========================== Real-Time group scheduling ==========================
Signature · 1 line
2.29.2
PATCH 5/10 docs/scheduler/sched-bwc: note/link cgroup v2
In reply to a message not in the archive--- Documentation/admin-guide/cgroup-v2.rst | 4 ++++ Documentation/scheduler/sched-bwc.rst | 5 +++++ 2 files changed, 9 insertions(+)
Documentation/admin-guide/cgroup-v2.rst +4 -0
@@ -1,3 +1,5 @@ +.. _cgroup-v2: + ================ Control Group v2 ================
@@ -954,6 +956,8 @@ All cgroup core files are prefixed with "cgroup." Controllers =========== +.. _cgroup-v2-cpu: + CPU ---
Documentation/scheduler/sched-bwc.rst +5 -0
@@ -27,6 +27,11 @@ Management ---------- Quota and period are managed within the cpu subsystem via cgroupfs. +.. note:: + The cgroupfs files described in this section are only applicable + to cgroup v1. For cgroup v2, see + :ref:`Documentation/admin-guide/cgroupv2.rst <cgroup-v2-cpu>`. + - cpu.cfs_quota_us: the total available run-time within a period (in microseconds) - cpu.cfs_period_us: the length of a period (in microseconds)
Signature · 1 line
2.29.2
PATCH 6/10 docs/admin-guide: cgroup-v2: typos and spaces
In reply to a message not in the archive- fix a typo (mempry -> memory) in a file name;
- add space before "(" where appropriate.
--- Documentation/admin-guide/cgroup-v2.rst | 34 ++++++++++++------------- 1 file changed, 17 insertions(+), 17 deletions(-)
Documentation/admin-guide/cgroup-v2.rst +17 -17
@@ -1263,9 +1263,9 @@ PAGE_SIZE multiple when read back. can show up in the middle. Don't rely on items remaining in a fixed position; use the keys to look up specific values! - If the entry has no per-node counter(or not show in the - mempry.numa_stat). We use 'npn'(non-per-node) as the tag - to indicate that it will not show in the mempry.numa_stat. + If the entry has no per-node counter (or not show in the + memory.numa_stat). We use 'npn' (non-per-node) as the tag + to indicate that it will not show in the memory.numa_stat. anon Amount of memory used in anonymous mappings such as
@@ -1281,11 +1281,11 @@ PAGE_SIZE multiple when read back. pagetables Amount of memory allocated for page tables. - percpu(npn) + percpu (npn) Amount of memory used for storing per-cpu kernel data structures. - sock(npn) + sock (npn) Amount of memory used in network transmission buffers shmem
@@ -1333,7 +1333,7 @@ PAGE_SIZE multiple when read back. Part of "slab" that cannot be reclaimed on memory pressure. - slab(npn) + slab (npn) Amount of memory used for storing in-kernel data structures.
@@ -1361,39 +1361,39 @@ PAGE_SIZE multiple when read back. workingset_nodereclaim Number of times a shadow node has been reclaimed - pgfault(npn) + pgfault (npn) Total number of page faults incurred - pgmajfault(npn) + pgmajfault (npn) Number of major page faults incurred - pgrefill(npn) + pgrefill (npn) Amount of scanned pages (in an active LRU list) - pgscan(npn) + pgscan (npn) Amount of scanned pages (in an inactive LRU list) - pgsteal(npn) + pgsteal (npn) Amount of reclaimed pages - pgactivate(npn) + pgactivate (npn) Amount of pages moved to the active LRU list - pgdeactivate(npn) + pgdeactivate (npn) Amount of pages moved to the inactive LRU list - pglazyfree(npn) + pglazyfree (npn) Amount of pages postponed to be freed under memory pressure - pglazyfreed(npn) + pglazyfreed (npn) Amount of reclaimed lazyfree pages - thp_fault_alloc(npn) + thp_fault_alloc (npn) Number of transparent hugepages which were allocated to satisfy a page fault. This counter is not present when CONFIG_TRANSPARENT_HUGEPAGE is not set. - thp_collapse_alloc(npn) + thp_collapse_alloc (npn) Number of transparent hugepages which were allocated to allow collapsing an existing range of pages. This counter is not present when CONFIG_TRANSPARENT_HUGEPAGE is not set.
Signature · 1 line
2.29.2
PATCH 7/10 docs/admin-guide: cgroup-v2: fix cgroup.type rendering
In reply to Kir KolyshkinDue to an extra vertical whitespace, this was not recognised as a definition list entry, and thus was not rendered like the rest of cgroupfs files.
--- Documentation/admin-guide/cgroup-v2.rst | 1 - 1 file changed, 1 deletion(-)
Documentation/admin-guide/cgroup-v2.rst +0 -1
@@ -788,7 +788,6 @@ Core Interface Files All cgroup core files are prefixed with "cgroup." cgroup.type - A read-write single value file which exists on non-root cgroups.
Signature · 1 line
2.29.2
PATCH 8/10 doc/admin-guide/cgroup-v2: use tables
In reply to Kir KolyshkinThese two places are rendered like a table in the source (rst) code, but they are seen as plain text by formatters, and thus are joined together into a single line, e.g.:
Quoted 1 line
“root” - a partition root “member” - a non-root member of a partition
This is definitely not what was intended.
To fix, use table formatting, like in other places.
--- Documentation/admin-guide/cgroup-v2.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-)
Documentation/admin-guide/cgroup-v2.rst +10 -6
@@ -2003,10 +2003,12 @@ Cpuset Interface Files cpuset-enabled cgroups. This flag is owned by the parent cgroup and is not delegatable. - It accepts only the following input values when written to. + It accepts only the following input values when written to. - "root" - a partition root - "member" - a non-root member of a partition + ======== ================================ + "root" a partition root + "member" a non-root member of a partition + ======== ================================ When set to be a partition root, the current cgroup is the root of a new partition or scheduling domain that comprises
@@ -2047,9 +2049,11 @@ Cpuset Interface Files root to change. On read, the "cpuset.sched.partition" file can show the following values. - "member" Non-root member of a partition - "root" Partition root - "root invalid" Invalid partition root + ============== ============================== + "member" Non-root member of a partition + "root" Partition root + "root invalid" Invalid partition root + ============== ============================== It is a partition root if the first 2 partition root conditions above are true and at least one CPU from "cpuset.cpus" is
Signature · 1 line
2.29.2
PATCH 9/10 docs/admin-guide/cgroup-v2: nit
In reply to a message not in the archiveImproper Capitalization.
--- Documentation/admin-guide/cgroup-v2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/admin-guide/cgroup-v2.rst +1 -1
@@ -2226,7 +2226,7 @@ Without cgroup namespace, the "/proc/$PID/cgroup" file shows the complete path of the cgroup of a process. In a container setup where a set of cgroups and namespaces are intended to isolate processes the "/proc/$PID/cgroup" file may leak potential system level information -to the isolated processes. For Example:: +to the isolated processes. For example:: # cat /proc/self/cgroup 0::/batchjobs/container_id1
Signature · 1 line
2.29.2
PATCH 10/10 docs/admin-guide/cgroup-v2: fix mount opt rendering
In reply to a message not in the archiveDue to an extra empty line between the option and its description it is rendered not like in other places.
Remove the empty lines to fix.
--- Documentation/admin-guide/cgroup-v2.rst | 3 --- 1 file changed, 3 deletions(-)
Documentation/admin-guide/cgroup-v2.rst +0 -3
@@ -174,7 +174,6 @@ disabling controllers in v1 and make them always available in v2. cgroup v2 currently supports the following mount options. nsdelegate - Consider cgroup namespaces as delegation boundaries. This option is system wide and can only be set on mount or modified through remount from the init namespace. The mount option is
@@ -182,7 +181,6 @@ cgroup v2 currently supports the following mount options. Delegation section for details. memory_localevents - Only populate memory.events with data for the current cgroup, and not any subtrees. This is legacy behaviour, the default behaviour without this option is to include subtree counts.
@@ -191,7 +189,6 @@ cgroup v2 currently supports the following mount options. option is ignored on non-init namespace mounts. memory_recursiveprot - Recursively apply memory.min and memory.low protection to entire subtrees, without requiring explicit downward propagation into leaf cgroups. This allows protecting entire
Signature · 1 line
2.29.2
Tejun Heo
Acked-byQuoted 9 lines · Kir Kolyshkin
These are mostly formatting fixes for a few cases where html looks plain wrong, plus a couple of added cross-references, and a typo.
All issues spotted while reading cgroup docs. Results are checked manually for both html and pdf, using both Sphinx 2.4.4 and 3.2.1 for rendering.
All commits are against docs-next@52042e2db
For the series,
I suppose it'd be best to route this through the doc tree?
Thanks.
Signature · 1 line
tejun
Re: [PATCH 04/10] docs/scheduler/sched-bwc: add proper ref
In reply to a message not in the archiveQuoted 27 lines · On Tue, 19 Jan 2021 16:18:18 -0800 Kir Kolyshkin…
Add a proper reference instead of just using the file name.
Signed-off-by Kir Kolyshkin <[email protected]>--- Documentation/scheduler/sched-bwc.rst | 3 ++- Documentation/scheduler/sched-rt-group.rst | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-)Documentation/scheduler/sched-bwc.rst +2
-1@@ -4,7 +4,8 @@ CFS Bandwidth Control .. note:: This document only discusses CPU bandwidth control for SCHED_NORMAL. - The SCHED_RT case is covered in Documentation/scheduler/sched-rt-group.rst + The SCHED_RT case is covered in + :ref:`Documentation/scheduler/sched-rt-group.rst <sched-rt-group>`. CFS bandwidth control is a CONFIG_FAIR_GROUP_SCHED extension which allows the specification of the maximum CPU bandwidth available to a group or hierarchy.Documentation/scheduler/sched-rt-group.rst +0
-0
Documentation/scheduler/sched-rt-group.rst line 2
Quoted 2 lines
Documentation/scheduler/sched-rt-group.rst +2
-0@@ -1,3 +1,5 @@ +.. _sched-rt-group: +
So why do you need to do this? The build system in recent kernels will generate that reference automatically without the extra markup.
Thanks,
jon
Quoted 5 lines · On Wed, 20 Jan 2021 11:43:46 -0500 Tejun Heo…
For the series,
Acked-by Tejun Heo <[email protected]>I suppose it'd be best to route this through the doc tree?
Works for me.
I've applied the set with the exception of #4, which still seems unnecessary to me; Kir, I can reconsider that if you want to argue the case.
Thanks,
jon