"Memory Resource Controller" CGroup v1 documentation has been in reST since
99c8b231ae6c6c ("docs: cgroup-v1: convert docs to ReST and rename to *.rst").
The current doc look is kinda ugly, so improve the formatting (only htmldocs is
tested).
Changes since v1 [1]:
* Drop the underline fix, since the blamed commit had been dropped
* Rebase on top of current cgroup tree (for-next branch)
Range-diff against v1:
1: e0f2b878ad6435 < -: -------------- docs: cgroup-v1: extend underline of section 8
2: 4e26b743ce9b42 = 1: cb31249cacdad6 docs: cgroup-v1: replace custom note constructs with appropriate admonition blocks
3: c89f9aa1e6dac9 < -: -------------- docs: cgroup-v1: wrap remaining admonitions in admonition blocks
-: -------------- > 2: 8e03baf289c4f2 docs: cgroup-v1: wrap remaining admonitions in admonition blocks
4: b901b2b0407e23 = 3: 790ac70bcf31e1 docs: cgroup-v1: use code block for locking order schema
5: f4112d2f9990ce = 4: 2af22c24977a38 docs: cgroup-v1: fix footnotes
6: d5d16831555e6b = 5: 9788d0e8c87cc5 docs: cgroup-v1: move hierarchy of accounting caption
7: 92db959851e2c8 = 6: b191e2bd87871b docs: cgroup-v1: use bullet lists for list of stat file tables
8: 767988658f58b8 ! 7: 56e4ba363e4e65 docs: cgroup-v1: use make swap extension subsections subsections
@@ Metadata
Author: Bagas Sanjaya <[email protected]>
## Commit message ##
- docs: cgroup-v1: use make swap extension subsections subsections
+ docs: cgroup-v1: make swap extension subsections subsections
Subsections text of swap extension section is marked up as bold text,
whereas making them proper subsection is more appropriate.
9: a502f09f9a3c33 ! 8: 6895ee7c84e840 docs: cgroup-v1: add internal cross-references
@@ Documentation/admin-guide/cgroup-v1/memory.rst: If we want to change this to 1G,
+.. _cgroup-v1-memory-move-charges:
+
- 8. Move charges at task migration (DEPRECATED!)
- ===============================================
+ 8. Move charges at task migration
+ =================================
@@ Documentation/admin-guide/cgroup-v1/memory.rst: If you want to enable it::
10: 895b1f1aa37d33 = 9: b179c2788f2a36 docs: cgroup-v1: use numbered lists for user interface setup
[1]: https://lore.kernel.org/linux-doc/[email protected]/
Bagas Sanjaya (9):
docs: cgroup-v1: replace custom note constructs with appropriate
admonition blocks
docs: cgroup-v1: wrap remaining admonitions in admonition blocks
docs: cgroup-v1: use code block for locking order schema
docs: cgroup-v1: fix footnotes
docs: cgroup-v1: move hierarchy of accounting caption
docs: cgroup-v1: use bullet lists for list of stat file tables
docs: cgroup-v1: make swap extension subsections subsections
docs: cgroup-v1: add internal cross-references
docs: cgroup-v1: use numbered lists for user interface setup
.../admin-guide/cgroup-v1/cgroups.rst | 2 +
.../admin-guide/cgroup-v1/memory.rst | 268 ++++++++++--------
2 files changed, 146 insertions(+), 124 deletions(-)
base-commit: 21786e5cb375a1e58a9175fee423e1d7f892d965
--
An old man doll... just what I always wanted! - Clara
The documentation contains references to other sections in the doc
(internal). Add cross-references for them so that these can be accessed
without having to manually search for them.
Signed-off-by: Bagas Sanjaya <[email protected]>
---
.../admin-guide/cgroup-v1/memory.rst | 43 +++++++++++++------
1 file changed, 30 insertions(+), 13 deletions(-)
diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst
index 0e583a6f783955..16d938abe69f81 100644
--- a/Documentation/admin-guide/cgroup-v1/memory.rst
+++ b/Documentation/admin-guide/cgroup-v1/memory.rst
@@ -55,7 +55,8 @@ Features:
- Root cgroup has no limit controls.
Kernel memory support is a work in progress, and the current version provides
- basically functionality. (See Section 2.7)
+ basically functionality. (See :ref:`section 2.7
+ <cgroup-v1-memory-kernel-extension>`)
Brief summary of control files.
@@ -221,8 +222,9 @@ behind this approach is that a cgroup that aggressively uses a shared
page will eventually get charged for it (once it is uncharged from
the cgroup that brought it in -- this will happen on memory pressure).
-But see section 8.2: when moving a task to another cgroup, its pages may
-be recharged to the new cgroup, if move_charge_at_immigrate has been chosen.
+But see :ref:`section 8.2 <cgroup-v1-memory-movable-charges>` when moving a
+task to another cgroup, its pages may be recharged to the new cgroup, if
+move_charge_at_immigrate has been chosen.
2.4 Swap Extension
--------------------------------------
@@ -270,7 +272,7 @@ global VM. When a cgroup goes over its limit, we first try
to reclaim memory from the cgroup so as to make space for the new
pages that the cgroup has touched. If the reclaim is unsuccessful,
an OOM routine is invoked to select and kill the bulkiest task in the
-cgroup. (See 10. OOM Control below.)
+cgroup. (See :ref:`10. OOM Control <cgroup-v1-memory-oom-control>` below.)
The reclaim algorithm has not been modified for cgroups, except that
pages that are selected for reclaiming come from the per-cgroup LRU
@@ -284,7 +286,7 @@ list.
When panic_on_oom is set to "2", the whole system will panic.
When oom event notifier is registered, event will be delivered.
-(See oom_control section)
+(See :ref:`oom_control <cgroup-v1-memory-oom-control>` section)
2.6 Locking
-----------
@@ -301,6 +303,8 @@ Per-node-per-memcgroup LRU (cgroup's private LRU) is guarded by
lruvec->lru_lock; PG_lru bit of page->flags is cleared before
isolating a page from its LRU under lruvec->lru_lock.
+.. _cgroup-v1-memory-kernel-extension:
+
2.7 Kernel Memory Extension
-----------------------------------------------
@@ -460,6 +464,8 @@ test because it has noise of shared objects/status.
But the above two are testing extreme situations.
Trying usual test under memory controller is always helpful.
+.. _cgroup-v1-memory-test-troubleshoot:
+
4.1 Troubleshooting
-------------------
@@ -472,8 +478,11 @@ terminated by the OOM killer. There are several causes for this:
A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of
some of the pages cached in the cgroup (page cache pages).
-To know what happens, disabling OOM_Kill as per "10. OOM Control" (below) and
-seeing what happens will be helpful.
+To know what happens, disabling OOM_Kill as per :ref:`"10. OOM Control"
+<cgroup-v1-memory-oom-control>` (below) and seeing what happens will be
+helpful.
+
+.. _cgroup-v1-memory-test-task-migration:
4.2 Task migration
------------------
@@ -484,15 +493,16 @@ remain charged to it, the charge is dropped when the page is freed or
reclaimed.
You can move charges of a task along with task migration.
-See 8. "Move charges at task migration"
+See :ref:`8. "Move charges at task migration" <cgroup-v1-memory-move-charges>`
4.3 Removing a cgroup
---------------------
-A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a
-cgroup might have some charge associated with it, even though all
-tasks have migrated away from it. (because we charge against pages, not
-against tasks.)
+A cgroup can be removed by rmdir, but as discussed in :ref:`sections 4.1
+<cgroup-v1-memory-test-troubleshoot>` and :ref:`4.2
+<cgroup-v1-memory-test-task-migration>`, a cgroup might have some charge
+associated with it, even though all tasks have migrated away from it. (because
+we charge against pages, not against tasks.)
We move the stats to parent, and no change on the charge except uncharging
from the child.
@@ -719,6 +729,8 @@ If we want to change this to 1G, we can at any time use::
It is recommended to set the soft limit always below the hard limit,
otherwise the hard limit will take precedence.
+.. _cgroup-v1-memory-move-charges:
+
8. Move charges at task migration
=================================
@@ -739,7 +751,8 @@ If you want to enable it::
.. note::
Each bits of move_charge_at_immigrate has its own meaning about what type
- of charges should be moved. See 8.2 for details.
+ of charges should be moved. See :ref:`section 8.2
+ <cgroup-v1-memory-movable-charges>` for details.
.. note::
Charges are moved only when you move mm->owner, in other words,
@@ -757,6 +770,8 @@ And if you want disable it again::
# echo 0 > memory.move_charge_at_immigrate
+.. _cgroup-v1-memory-movable-charges:
+
8.2 Type of charges which can be moved
--------------------------------------
@@ -806,6 +821,8 @@ threshold in any direction.
It's applicable for root and non-root cgroup.
+.. _cgroup-v1-memory-oom-control:
+
10. OOM Control
===============
--
An old man doll... just what I always wanted! - Clara
On Thu, Jan 05, 2023 at 08:16:25PM +0700, Bagas Sanjaya wrote:
> "Memory Resource Controller" CGroup v1 documentation has been in reST since
> 99c8b231ae6c6c ("docs: cgroup-v1: convert docs to ReST and rename to *.rst").
> The current doc look is kinda ugly, so improve the formatting (only htmldocs is
> tested).
Applied to cgroup/for-6.2-fixes.
Thanks.
--
tejun