Skip to contentSkip to conversation

docs: cgroup nits and fixes

PATCH In review Kir Kolyshkin 4 participants 14 messages Jan 20, 2021 – Jan 21, 2021 3 messages not in the archive

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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

A message that is not in the archive (sent off-list or not yet received): 20210120001824.385168-1-kolyshkin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org

#2 lore raw

PATCH 1/10 docs/scheduler/sched-bwc: formatting fix

Since 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
index 9801d6b284b1..4af4ee1f3600 100644
@@ -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
#3 lore raw

PATCH 4/10 docs/scheduler/sched-bwc: add proper ref

In reply to a message not in the archive

Add 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
index a44860d33ffc..dcec7440c222 100644
@@ -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
index 655a096ec8fb..a3b4aa51c271 100644
@@ -1,3 +1,5 @@
+.. _sched-rt-group:
+
 ==========================
 Real-Time group scheduling
 ==========================
Signature · 1 line
2.29.2

A message that is not in the archive (sent off-list or not yet received): 20210120001824.385168-5-kolyshkin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org

#5 lore raw

Re: [PATCH 04/10] docs/scheduler/sched-bwc: add proper ref

Quoted 27 lines · On Tue, 19 Jan 2021 16:18:18 -0800 Kir Kolyshkin…

Add 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
index a44860d33ffc..dcec7440c222 100644
@@ -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
index 655a096ec8fb..a3b4aa51c271 100644

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

#6 lore raw

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
index e0f6ff7cfa93..b55362454886 100644
@@ -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
index dcec7440c222..963fde3993dc 100644
@@ -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
#7 lore raw

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.

Fixes 5f9a4f4a70960
---
 Documentation/admin-guide/cgroup-v2.rst | 34 ++++++++++++-------------
 1 file changed, 17 insertions(+), 17 deletions(-)
Documentation/admin-guide/cgroup-v2.rst +17 -17
index b55362454886..073f976d44ea 100644
@@ -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
#8 lore raw

PATCH 9/10 docs/admin-guide/cgroup-v2: nit

In reply to a message not in the archive

Improper Capitalization.

---
 Documentation/admin-guide/cgroup-v2.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/admin-guide/cgroup-v2.rst +1 -1
index 6f59f13f28d0..136902cd0e98 100644
@@ -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
#9 lore raw

PATCH 10/10 docs/admin-guide/cgroup-v2: fix mount opt rendering

In reply to a message not in the archive

Due 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
index 136902cd0e98..14a7523c46a4 100644
@@ -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
Acked-by
#10 lore raw
In reply to a message not in the archive
Quoted 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

A message that is not in the archive (sent off-list or not yet received): [email protected]

#12 lore raw
Quoted 5 lines · On Wed, 20 Jan 2021 11:43:46 -0500 Tejun Heo…

For the series,

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

#13 lore raw

PATCH 2/10 docs/scheduler/sched-design-CFS: formatting fix

In reply to Kir Kolyshkin

Fix 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
index a96c72651877..59b2d1fb4dc4 100644
@@ -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
#14 lore raw

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
index 4af4ee1f3600..a44860d33ffc 100644
@@ -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
#15 lore raw

PATCH 7/10 docs/admin-guide: cgroup-v2: fix cgroup.type rendering

In reply to Kir Kolyshkin

Due 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
index 073f976d44ea..c1b6ffc286cf 100644
@@ -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
#16 lore raw

PATCH 8/10 doc/admin-guide/cgroup-v2: use tables

In reply to Kir Kolyshkin

These 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
index c1b6ffc286cf..6f59f13f28d0 100644
@@ -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