Re: [PATCH rfc 2/3] docs: cgroup-v1: reflect the deprecation of the non-hierarchical mode

[Michal Hocko <mhocko@suse.com>]

On Tue 03-11-20 13:27:24, Roman Gushchin wrote:
> Update cgroup v1 docs after the deprecation of the non-hierarchical
> mode of the memory controller.
> 
> Signed-off-by: Roman Gushchin <guro@fb.com>

Acked-by: Michal Hocko <mhocko@suse.com>

> ---
>  .../admin-guide/cgroup-v1/memcg_test.rst      |  8 ++--
>  .../admin-guide/cgroup-v1/memory.rst          | 40 ++++++-------------
>  2 files changed, 16 insertions(+), 32 deletions(-)
> 
> diff --git a/Documentation/admin-guide/cgroup-v1/memcg_test.rst b/Documentation/admin-guide/cgroup-v1/memcg_test.rst
> index 3f7115e07b5d..4f83de2dab6e 100644
> --- a/Documentation/admin-guide/cgroup-v1/memcg_test.rst
> +++ b/Documentation/admin-guide/cgroup-v1/memcg_test.rst
> @@ -219,13 +219,11 @@ Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y.
>  
>  	This is an easy way to test page migration, too.
>  
> -9.5 mkdir/rmdir
> ----------------
> +9.5 nested cgroups
> +------------------
>  
> -	When using hierarchy, mkdir/rmdir test should be done.
> -	Use tests like the following::
> +	Use tests like the following for testing nested cgroups::
>  
> -		echo 1 >/opt/cgroup/01/memory/use_hierarchy
>  		mkdir /opt/cgroup/01/child_a
>  		mkdir /opt/cgroup/01/child_b
>  
> diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst
> index 12757e63b26c..a44cd467d218 100644
> --- a/Documentation/admin-guide/cgroup-v1/memory.rst
> +++ b/Documentation/admin-guide/cgroup-v1/memory.rst
> @@ -77,6 +77,8 @@ Brief summary of control files.
>   memory.soft_limit_in_bytes	     set/show soft limit of memory usage
>   memory.stat			     show various statistics
>   memory.use_hierarchy		     set/show hierarchical account enabled
> +                                     This knob is deprecated and shouldn't be
> +                                     used.
>   memory.force_empty		     trigger forced page reclaim
>   memory.pressure_level		     set memory pressure notifications
>   memory.swappiness		     set/show swappiness parameter of vmscan
> @@ -495,16 +497,13 @@ 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 root (if use_hierarchy==0) or parent (if
> -use_hierarchy==1), and no change on the charge except uncharging
> +We move the stats to parent, and no change on the charge except uncharging
>  from the child.
>  
>  Charges recorded in swap information is not updated at removal of cgroup.
>  Recorded information is discarded and a cgroup which uses swap (swapcache)
>  will be charged as a new owner of it.
>  
> -About use_hierarchy, see Section 6.
> -
>  5. Misc. interfaces
>  ===================
>  
> @@ -527,8 +526,6 @@ About use_hierarchy, see Section 6.
>    write will still return success. In this case, it is expected that
>    memory.kmem.usage_in_bytes == memory.usage_in_bytes.
>  
> -  About use_hierarchy, see Section 6.
> -
>  5.2 stat file
>  -------------
>  
> @@ -675,31 +672,20 @@ hierarchy::
>  		      d   e
>  
>  In the diagram above, with hierarchical accounting enabled, all memory
> -usage of e, is accounted to its ancestors up until the root (i.e, c and root),
> -that has memory.use_hierarchy enabled. If one of the ancestors goes over its
> -limit, the reclaim algorithm reclaims from the tasks in the ancestor and the
> -children of the ancestor.
> -
> -6.1 Enabling hierarchical accounting and reclaim
> -------------------------------------------------
> -
> -A memory cgroup by default disables the hierarchy feature. Support
> -can be enabled by writing 1 to memory.use_hierarchy file of the root cgroup::
> +usage of e, is accounted to its ancestors up until the root (i.e, c and root).
> +If one of the ancestors goes over its limit, the reclaim algorithm reclaims
> +from the tasks in the ancestor and the children of the ancestor.
>  
> -	# echo 1 > memory.use_hierarchy
> -
> -The feature can be disabled by::
> +6.1 Hierarchical accounting and reclaim
> +---------------------------------------
>  
> -	# echo 0 > memory.use_hierarchy
> +Hierarchical accounting is enabled by default. Disabling the hierarchical
> +accounting is deprecated. An attempt to do it will result in a failure
> +and a warning printed to dmesg.
>  
> -NOTE1:
> -       Enabling/disabling will fail if either the cgroup already has other
> -       cgroups created below it, or if the parent cgroup has use_hierarchy
> -       enabled.
> +For compatibility reasons writing 1 to memory.use_hierarchy will always pass::
>  
> -NOTE2:
> -       When panic_on_oom is set to "2", the whole system will panic in
> -       case of an OOM event in any cgroup.
> +	# echo 1 > memory.use_hierarchy
>  
>  7. Soft limits
>  ==============
> -- 
> 2.26.2

-- 
Michal Hocko
SUSE Labs