[PATCH 00/10] docs: cgroup nits and fixes

[PATCH 00/10] docs: cgroup nits and fixes

[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

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(-)

-- 
2.29.2

[PATCH 00/10] docs: cgroup nits and fixes

[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

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(-)

-- 
2.29.2

[PATCH 01/10] docs/scheduler/sched-bwc: formatting fix

[Kir Kolyshkin]

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.

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 Documentation/scheduler/sched-bwc.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
index 9801d6b284b1..4af4ee1f3600 100644
--- a/Documentation/scheduler/sched-bwc.rst
+++ b/Documentation/scheduler/sched-bwc.rst
@@ -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::
 
-- 
2.29.2

[PATCH 01/10] docs/scheduler/sched-bwc: formatting fix

[Kir Kolyshkin]

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.

Signed-off-by: Kir Kolyshkin <kolyshkin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
 Documentation/scheduler/sched-bwc.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
index 9801d6b284b1..4af4ee1f3600 100644
--- a/Documentation/scheduler/sched-bwc.rst
+++ b/Documentation/scheduler/sched-bwc.rst
@@ -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::
 
-- 
2.29.2

[PATCH 02/10] docs/scheduler/sched-design-CFS: formatting fix

[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.

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 Documentation/scheduler/sched-design-CFS.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/scheduler/sched-design-CFS.rst b/Documentation/scheduler/sched-design-CFS.rst
index a96c72651877..59b2d1fb4dc4 100644
--- a/Documentation/scheduler/sched-design-CFS.rst
+++ b/Documentation/scheduler/sched-design-CFS.rst
@@ -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
-- 
2.29.2

[PATCH 03/10] docs/scheduler/sched-bwc: fix note rendering

[Kir Kolyshkin]

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 Documentation/scheduler/sched-bwc.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
index 4af4ee1f3600..a44860d33ffc 100644
--- a/Documentation/scheduler/sched-bwc.rst
+++ b/Documentation/scheduler/sched-bwc.rst
@@ -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.
-- 
2.29.2

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

[Kir Kolyshkin]

Add a proper reference instead of just using the file name.

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 Documentation/scheduler/sched-bwc.rst      | 3 ++-
 Documentation/scheduler/sched-rt-group.rst | 2 ++
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
index a44860d33ffc..dcec7440c222 100644
--- a/Documentation/scheduler/sched-bwc.rst
+++ b/Documentation/scheduler/sched-bwc.rst
@@ -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.
diff --git a/Documentation/scheduler/sched-rt-group.rst b/Documentation/scheduler/sched-rt-group.rst
index 655a096ec8fb..a3b4aa51c271 100644
--- a/Documentation/scheduler/sched-rt-group.rst
+++ b/Documentation/scheduler/sched-rt-group.rst
@@ -1,3 +1,5 @@
+.. _sched-rt-group:
+
 ==========================
 Real-Time group scheduling
 ==========================
-- 
2.29.2

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

[Kir Kolyshkin]

Add a proper reference instead of just using the file name.

Signed-off-by: Kir Kolyshkin <kolyshkin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
 Documentation/scheduler/sched-bwc.rst      | 3 ++-
 Documentation/scheduler/sched-rt-group.rst | 2 ++
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
index a44860d33ffc..dcec7440c222 100644
--- a/Documentation/scheduler/sched-bwc.rst
+++ b/Documentation/scheduler/sched-bwc.rst
@@ -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.
diff --git a/Documentation/scheduler/sched-rt-group.rst b/Documentation/scheduler/sched-rt-group.rst
index 655a096ec8fb..a3b4aa51c271 100644
--- a/Documentation/scheduler/sched-rt-group.rst
+++ b/Documentation/scheduler/sched-rt-group.rst
@@ -1,3 +1,5 @@
+.. _sched-rt-group:
+
 ==========================
 Real-Time group scheduling
 ==========================
-- 
2.29.2

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

[Jonathan Corbet]

On Tue, 19 Jan 2021 16:18:18 -0800
Kir Kolyshkin <kolyshkin@gmail.com> wrote:

> Add a proper reference instead of just using the file name.
> 
> Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
> ---
>  Documentation/scheduler/sched-bwc.rst      | 3 ++-
>  Documentation/scheduler/sched-rt-group.rst | 2 ++
>  2 files changed, 4 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
> index a44860d33ffc..dcec7440c222 100644
> --- a/Documentation/scheduler/sched-bwc.rst
> +++ b/Documentation/scheduler/sched-bwc.rst
> @@ -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.
> diff --git a/Documentation/scheduler/sched-rt-group.rst b/Documentation/scheduler/sched-rt-group.rst
> index 655a096ec8fb..a3b4aa51c271 100644
> --- a/Documentation/scheduler/sched-rt-group.rst
> +++ b/Documentation/scheduler/sched-rt-group.rst
> @@ -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

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

[Jonathan Corbet]

On Tue, 19 Jan 2021 16:18:18 -0800
Kir Kolyshkin <kolyshkin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

> Add a proper reference instead of just using the file name.
> 
> Signed-off-by: Kir Kolyshkin <kolyshkin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> ---
>  Documentation/scheduler/sched-bwc.rst      | 3 ++-
>  Documentation/scheduler/sched-rt-group.rst | 2 ++
>  2 files changed, 4 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
> index a44860d33ffc..dcec7440c222 100644
> --- a/Documentation/scheduler/sched-bwc.rst
> +++ b/Documentation/scheduler/sched-bwc.rst
> @@ -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.
> diff --git a/Documentation/scheduler/sched-rt-group.rst b/Documentation/scheduler/sched-rt-group.rst
> index 655a096ec8fb..a3b4aa51c271 100644
> --- a/Documentation/scheduler/sched-rt-group.rst
> +++ b/Documentation/scheduler/sched-rt-group.rst
> @@ -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

[PATCH 05/10] docs/scheduler/sched-bwc: note/link cgroup v2

[Kir Kolyshkin]

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 Documentation/admin-guide/cgroup-v2.rst | 4 ++++
 Documentation/scheduler/sched-bwc.rst   | 5 +++++
 2 files changed, 9 insertions(+)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index e0f6ff7cfa93..b55362454886 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -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
 ---
 
diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
index dcec7440c222..963fde3993dc 100644
--- a/Documentation/scheduler/sched-bwc.rst
+++ b/Documentation/scheduler/sched-bwc.rst
@@ -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)
-- 
2.29.2

[PATCH 05/10] docs/scheduler/sched-bwc: note/link cgroup v2

[Kir Kolyshkin]

Signed-off-by: Kir Kolyshkin <kolyshkin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
 Documentation/admin-guide/cgroup-v2.rst | 4 ++++
 Documentation/scheduler/sched-bwc.rst   | 5 +++++
 2 files changed, 9 insertions(+)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index e0f6ff7cfa93..b55362454886 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -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
 ---
 
diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
index dcec7440c222..963fde3993dc 100644
--- a/Documentation/scheduler/sched-bwc.rst
+++ b/Documentation/scheduler/sched-bwc.rst
@@ -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)
-- 
2.29.2

[PATCH 06/10] docs/admin-guide: cgroup-v2: typos and spaces

[Kir Kolyshkin]

- fix a typo (mempry -> memory) in a file name;
- add space before "(" where appropriate.

Fixes: 5f9a4f4a70960
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 Documentation/admin-guide/cgroup-v2.rst | 34 ++++++++++++-------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index b55362454886..073f976d44ea 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -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.
-- 
2.29.2

[PATCH 06/10] docs/admin-guide: cgroup-v2: typos and spaces

[Kir Kolyshkin]

- fix a typo (mempry -> memory) in a file name;
- add space before "(" where appropriate.

Fixes: 5f9a4f4a70960
Signed-off-by: Kir Kolyshkin <kolyshkin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
 Documentation/admin-guide/cgroup-v2.rst | 34 ++++++++++++-------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index b55362454886..073f976d44ea 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -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.
-- 
2.29.2

[PATCH 07/10] docs/admin-guide: cgroup-v2: fix cgroup.type rendering

[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.

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 Documentation/admin-guide/cgroup-v2.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 073f976d44ea..c1b6ffc286cf 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -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.
 
-- 
2.29.2

[PATCH 08/10] doc/admin-guide/cgroup-v2: use tables

[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.:

> “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.

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 Documentation/admin-guide/cgroup-v2.rst | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index c1b6ffc286cf..6f59f13f28d0 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -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
-- 
2.29.2

[PATCH 09/10] docs/admin-guide/cgroup-v2: nit

[Kir Kolyshkin]

Improper Capitalization.

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 Documentation/admin-guide/cgroup-v2.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 6f59f13f28d0..136902cd0e98 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -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
-- 
2.29.2

[PATCH 09/10] docs/admin-guide/cgroup-v2: nit

[Kir Kolyshkin]

Improper Capitalization.

Signed-off-by: Kir Kolyshkin <kolyshkin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
 Documentation/admin-guide/cgroup-v2.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 6f59f13f28d0..136902cd0e98 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -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
-- 
2.29.2

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

[Kir Kolyshkin]

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.

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 Documentation/admin-guide/cgroup-v2.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 136902cd0e98..14a7523c46a4 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -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
-- 
2.29.2

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

[Kir Kolyshkin]

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.

Signed-off-by: Kir Kolyshkin <kolyshkin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
 Documentation/admin-guide/cgroup-v2.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 136902cd0e98..14a7523c46a4 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -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
-- 
2.29.2

Re: [PATCH 00/10] docs: cgroup nits and fixes

[Tejun Heo]

On Tue, Jan 19, 2021 at 04:18:14PM -0800, Kir Kolyshkin wrote:
> 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,

Acked-by: Tejun Heo <tj@kernel.org>

I suppose it'd be best to route this through the doc tree?

Thanks.

-- 
tejun

Re: [PATCH 00/10] docs: cgroup nits and fixes

[Tejun Heo]

On Tue, Jan 19, 2021 at 04:18:14PM -0800, Kir Kolyshkin wrote:
> 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,

Acked-by: Tejun Heo <tj-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>

I suppose it'd be best to route this through the doc tree?

Thanks.

-- 
tejun

Re: [PATCH 00/10] docs: cgroup nits and fixes

[Jonathan Corbet]

On Wed, 20 Jan 2021 11:43:46 -0500
Tejun Heo <tj@kernel.org> wrote:

> For the series,
> 
> Acked-by: Tejun Heo <tj@kernel.org>
> 
> 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

Re: [PATCH 00/10] docs: cgroup nits and fixes

[Jonathan Corbet]

On Wed, 20 Jan 2021 11:43:46 -0500
Tejun Heo <tj-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:

> For the series,
> 
> Acked-by: Tejun Heo <tj-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> 
> 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