[PATCH] memcg: Fix documentation

[PATCH] memcg: Fix documentation

[Bharata B Rao]

memcg: Fix documentation.

The description about various statistics from memory.stat is not accurate
and confusing at times.

Correct this along with a few other minor cleanups.

Signed-off-by: Bharata B Rao <bharata@linux.vnet.ibm.com>
Cc: Balbir Singh <balbir@linux.vnet.ibm.com>
Cc: KAMEZAWA Hiroyuki <kamezawa.hiroyu@jp.fujitsu.com>
Cc: Andrew Morton <akpm@linux-foundation.org>
---
 Documentation/cgroups/memory.txt |   50 +++++++++++++++++++++------------------
 1 file changed, 28 insertions(+), 22 deletions(-)

--- a/Documentation/cgroups/memory.txt
+++ b/Documentation/cgroups/memory.txt
@@ -6,15 +6,14 @@ used here with the memory controller tha
 
 Salient features
 
-a. Enable control of both RSS (mapped) and Page Cache (unmapped) pages
+a. Enable control of RSS (mapped), Page Cache (unmapped) and Swap cache
+   (unmapped) pages.
 b. The infrastructure allows easy addition of other types of memory to control
 c. Provides *zero overhead* for non memory controller users
 d. Provides a double LRU: global memory pressure causes reclaim from the
    global LRU; a cgroup on hitting a limit, reclaims from the per
    cgroup LRU
 
-NOTE: Swap Cache (unmapped) is not accounted now.
-
 Benefits and Purpose of the memory controller
 
 The memory controller isolates the memory behaviour of a group of tasks
@@ -290,34 +289,41 @@ will be charged as a new owner of it.
   moved to the parent. If you want to avoid that, force_empty will be useful.
 
 5.2 stat file
-  memory.stat file includes following statistics (now)
-	cache			- # of pages from page-cache and shmem.
-	rss			- # of pages from anonymous memory.
-	pgpgin			- # of event of charging
-	pgpgout			- # of event of uncharging
-	active_anon		- # of pages on active lru of anon, shmem.
-	inactive_anon 		- # of pages on active lru of anon, shmem
-	active_file		- # of pages on active lru of file-cache
-	inactive_file		- # of pages on inactive lru of file cache
-	unevictable		- # of pages cannot be reclaimed.(mlocked etc)
-
-	Below is depend on CONFIG_DEBUG_VM.
-	inactive_ratio		- VM inernal parameter. (see mm/page_alloc.c)
-	recent_rotated_anon	- VM internal parameter. (see mm/vmscan.c)
-	recent_rotated_file	- VM internal parameter. (see mm/vmscan.c)
-	recent_scanned_anon 	- VM internal parameter. (see mm/vmscan.c)
-	recent_scanned_file 	- VM internal parameter. (see mm/vmscan.c)
 
-  Memo:
+memory.stat file includes following statistics
+
+cache		- # of bytes of page-cache memory.
+rss		- # of bytes of anonymous memory.
+pgpgin		- # of pages paged in (equivalent to # of charging events).
+pgpgout		- # of pages paged out (equivalent to # of uncharging events).
+active_anon	- # of bytes of anonymous memory on active lru list.
+inactive_anon	- # of bytes of anonymous memory on inactive lru list.
+active_file	- # of bytes of file-backed memory on active lru list.
+inactive_file	- # of bytes of file-backed memory on inactive lru list.
+unevictable	- # of bytes of memory that cannot be reclaimed (mlocked etc).
+
+The following additional stats are dependent on CONFIG_DEBUG_VM.
+
+inactive_ratio		- VM inernal parameter. (see mm/page_alloc.c)
+recent_rotated_anon	- VM internal parameter. (see mm/vmscan.c)
+recent_rotated_file	- VM internal parameter. (see mm/vmscan.c)
+recent_scanned_anon	- VM internal parameter. (see mm/vmscan.c)
+recent_scanned_file	- VM internal parameter. (see mm/vmscan.c)
+
+Memo:
 	recent_rotated means recent frequency of lru rotation.
 	recent_scanned means recent # of scans to lru.
 	showing for better debug please see the code for meanings.
 
+Note:
+	Only anonymous memory is listed as part of 'rss' stat. This should
+	not be confused with the true 'resident set size' or the amount of
+	physical memory used by the cgroup.
 
 5.3 swappiness
   Similar to /proc/sys/vm/swappiness, but affecting a hierarchy of groups only.
 
-  Following cgroup's swapiness can't be changed.
+  Following cgroups' swapiness can't be changed.
   - root cgroup (uses /proc/sys/vm/swappiness).
   - a cgroup which uses hierarchy and it has child cgroup.
   - a cgroup which uses hierarchy and not the root of hierarchy.

Re: [PATCH] memcg: Fix documentation

[KAMEZAWA Hiroyuki]

Thank you, very helpful. but some nitpicks.


On Wed, 8 Apr 2009 12:48:17 +0530
Bharata B Rao <bharata@linux.vnet.ibm.com> wrote:

> memcg: Fix documentation.
> 
> The description about various statistics from memory.stat is not accurate
> and confusing at times.
> 
> Correct this along with a few other minor cleanups.
> 
> Signed-off-by: Bharata B Rao <bharata@linux.vnet.ibm.com>
> Cc: Balbir Singh <balbir@linux.vnet.ibm.com>
> Cc: KAMEZAWA Hiroyuki <kamezawa.hiroyu@jp.fujitsu.com>
> Cc: Andrew Morton <akpm@linux-foundation.org>
> ---
>  Documentation/cgroups/memory.txt |   50 +++++++++++++++++++++------------------
>  1 file changed, 28 insertions(+), 22 deletions(-)
> 
> --- a/Documentation/cgroups/memory.txt
> +++ b/Documentation/cgroups/memory.txt
> @@ -6,15 +6,14 @@ used here with the memory controller tha
>  
>  Salient features
>  
> -a. Enable control of both RSS (mapped) and Page Cache (unmapped) pages
> +a. Enable control of RSS (mapped), Page Cache (unmapped) and Swap cache
> +   (unmapped) pages.
      Enable control of Anonymous memory, Page Cache and Swap Cache. 
?

>  b. The infrastructure allows easy addition of other types of memory to control
>  c. Provides *zero overhead* for non memory controller users
>  d. Provides a double LRU: global memory pressure causes reclaim from the
>     global LRU; a cgroup on hitting a limit, reclaims from the per
>     cgroup LRU
>  
> -NOTE: Swap Cache (unmapped) is not accounted now.
> -
>  Benefits and Purpose of the memory controller
>  
>  The memory controller isolates the memory behaviour of a group of tasks
> @@ -290,34 +289,41 @@ will be charged as a new owner of it.
>    moved to the parent. If you want to avoid that, force_empty will be useful.
>  
>  5.2 stat file
> -  memory.stat file includes following statistics (now)
> -	cache			- # of pages from page-cache and shmem.
> -	rss			- # of pages from anonymous memory.
> -	pgpgin			- # of event of charging
> -	pgpgout			- # of event of uncharging
> -	active_anon		- # of pages on active lru of anon, shmem.
> -	inactive_anon 		- # of pages on active lru of anon, shmem
> -	active_file		- # of pages on active lru of file-cache
> -	inactive_file		- # of pages on inactive lru of file cache
> -	unevictable		- # of pages cannot be reclaimed.(mlocked etc)
> -
> -	Below is depend on CONFIG_DEBUG_VM.
> -	inactive_ratio		- VM inernal parameter. (see mm/page_alloc.c)
> -	recent_rotated_anon	- VM internal parameter. (see mm/vmscan.c)
> -	recent_rotated_file	- VM internal parameter. (see mm/vmscan.c)
> -	recent_scanned_anon 	- VM internal parameter. (see mm/vmscan.c)
> -	recent_scanned_file 	- VM internal parameter. (see mm/vmscan.c)
>  
> -  Memo:
> +memory.stat file includes following statistics
> +
> +cache		- # of bytes of page-cache memory.
> +rss		- # of bytes of anonymous memory.
                    This includes # of swap cache.

> +pgpgin		- # of pages paged in (equivalent to # of charging events).
> +pgpgout		- # of pages paged out (equivalent to # of uncharging events).
> +active_anon	- # of bytes of anonymous memory on active lru list.
                                anonymous memory + shared memory(tmpfs) + SwapCache.
                          Seeing acitive/inactive_file, how about swap-backed memory ?

> +inactive_anon	- # of bytes of anonymous memory on inactive lru list. 
> +active_file	- # of bytes of file-backed memory on active lru list.
> +inactive_file	- # of bytes of file-backed memory on inactive lru list.
> +unevictable	- # of bytes of memory that cannot be reclaimed (mlocked etc).
> +
> +The following additional stats are dependent on CONFIG_DEBUG_VM.
> +
> +inactive_ratio		- VM inernal parameter. (see mm/page_alloc.c)
> +recent_rotated_anon	- VM internal parameter. (see mm/vmscan.c)
> +recent_rotated_file	- VM internal parameter. (see mm/vmscan.c)
> +recent_scanned_anon	- VM internal parameter. (see mm/vmscan.c)
> +recent_scanned_file	- VM internal parameter. (see mm/vmscan.c)
> +
> +Memo:
>  	recent_rotated means recent frequency of lru rotation.
>  	recent_scanned means recent # of scans to lru.
>  	showing for better debug please see the code for meanings.
>  
> +Note:
> +	Only anonymous memory is listed as part of 'rss' stat. This should
> +	not be confused with the true 'resident set size' or the amount of
> +	physical memory used by the cgroup.
        To know the real value of resident-set-size, plz check each process's
        anon_rss and file_rss. per-cgroup rss accounting is not done now.

Thanks,
-Kame

Re: [PATCH] memcg: Fix documentation

[Bharata B Rao]

On Wed, Apr 08, 2009 at 04:25:28PM +0900, KAMEZAWA Hiroyuki wrote:
> Thank you, very helpful. but some nitpicks.
> 
> 
> On Wed, 8 Apr 2009 12:48:17 +0530
> Bharata B Rao <bharata@linux.vnet.ibm.com> wrote:
> 
> > memcg: Fix documentation.
> > 
> > The description about various statistics from memory.stat is not accurate
> > and confusing at times.
> > 
> > Correct this along with a few other minor cleanups.
> > 
> > Signed-off-by: Bharata B Rao <bharata@linux.vnet.ibm.com>
> > Cc: Balbir Singh <balbir@linux.vnet.ibm.com>
> > Cc: KAMEZAWA Hiroyuki <kamezawa.hiroyu@jp.fujitsu.com>
> > Cc: Andrew Morton <akpm@linux-foundation.org>
> > ---
> >  Documentation/cgroups/memory.txt |   50 +++++++++++++++++++++------------------
> >  1 file changed, 28 insertions(+), 22 deletions(-)
> > 
> > --- a/Documentation/cgroups/memory.txt
> > +++ b/Documentation/cgroups/memory.txt
> > @@ -6,15 +6,14 @@ used here with the memory controller tha
> >  
> >  Salient features
> >  
> > -a. Enable control of both RSS (mapped) and Page Cache (unmapped) pages
> > +a. Enable control of RSS (mapped), Page Cache (unmapped) and Swap cache
> > +   (unmapped) pages.
>       Enable control of Anonymous memory, Page Cache and Swap Cache. 
> ?

I feel without the terms 'mapped' and 'unmaapped', the story of the memory
controller is not complete :)

> 
> >  b. The infrastructure allows easy addition of other types of memory to control
> >  c. Provides *zero overhead* for non memory controller users
> >  d. Provides a double LRU: global memory pressure causes reclaim from the
> >     global LRU; a cgroup on hitting a limit, reclaims from the per
> >     cgroup LRU
> >  
> > -NOTE: Swap Cache (unmapped) is not accounted now.
> > -
> >  Benefits and Purpose of the memory controller
> >  
> >  The memory controller isolates the memory behaviour of a group of tasks
> > @@ -290,34 +289,41 @@ will be charged as a new owner of it.
> >    moved to the parent. If you want to avoid that, force_empty will be useful.
> >  
> >  5.2 stat file
> > -  memory.stat file includes following statistics (now)
> > -	cache			- # of pages from page-cache and shmem.
> > -	rss			- # of pages from anonymous memory.
> > -	pgpgin			- # of event of charging
> > -	pgpgout			- # of event of uncharging
> > -	active_anon		- # of pages on active lru of anon, shmem.
> > -	inactive_anon 		- # of pages on active lru of anon, shmem
> > -	active_file		- # of pages on active lru of file-cache
> > -	inactive_file		- # of pages on inactive lru of file cache
> > -	unevictable		- # of pages cannot be reclaimed.(mlocked etc)
> > -
> > -	Below is depend on CONFIG_DEBUG_VM.
> > -	inactive_ratio		- VM inernal parameter. (see mm/page_alloc.c)
> > -	recent_rotated_anon	- VM internal parameter. (see mm/vmscan.c)
> > -	recent_rotated_file	- VM internal parameter. (see mm/vmscan.c)
> > -	recent_scanned_anon 	- VM internal parameter. (see mm/vmscan.c)
> > -	recent_scanned_file 	- VM internal parameter. (see mm/vmscan.c)
> >  
> > -  Memo:
> > +memory.stat file includes following statistics
> > +
> > +cache		- # of bytes of page-cache memory.
> > +rss		- # of bytes of anonymous memory.
>                     This includes # of swap cache.

Ok, will add that.

> 
> > +pgpgin		- # of pages paged in (equivalent to # of charging events).
> > +pgpgout		- # of pages paged out (equivalent to # of uncharging events).
> > +active_anon	- # of bytes of anonymous memory on active lru list.
>                                 anonymous memory + shared memory(tmpfs) + SwapCache.

Ok.

>                           Seeing acitive/inactive_file, how about swap-backed memory ?

Not sure what you are hinting at here.

Will post a new patch with the above changes. Thanks for your review.

Regards,
Bharata.

Re: [PATCH] memcg: Fix documentation

[KAMEZAWA Hiroyuki]

On Wed, 8 Apr 2009 14:03:27 +0530
Bharata B Rao <bharata@linux.vnet.ibm.com> wrote:

> > > -a. Enable control of both RSS (mapped) and Page Cache (unmapped) pages
> > > +a. Enable control of RSS (mapped), Page Cache (unmapped) and Swap cache
> > > +   (unmapped) pages.
> >       Enable control of Anonymous memory, Page Cache and Swap Cache. 
> > ?
> 
> I feel without the terms 'mapped' and 'unmaapped', the story of the memory
> controller is not complete :)
> 
Hmm ?.
     Anonymoys memory, File Cache(both of mapped/unmapped), SwapCache.
(At doing user support, explaining SwapCache is difficult sometimes ;)

I don't have serious concern, anyway.


> > 
> > > +pgpgin		- # of pages paged in (equivalent to # of charging events).
> > > +pgpgout		- # of pages paged out (equivalent to # of uncharging events).
> > > +active_anon	- # of bytes of anonymous memory on active lru list.
> >                                 anonymous memory + shared memory(tmpfs) + SwapCache.
> 
> Ok.
> 
> >                           Seeing acitive/inactive_file, how about swap-backed memory ?
> 
> Not sure what you are hinting at here.
> 
Ah, sorry. I just thought swap-backed v.s. file-backed pages explains all.

Thanks,
-Kame

Re: [PATCH] memcg: Fix documentation

[Bharata B Rao]

On Wed, Apr 08, 2009 at 04:25:28PM +0900, KAMEZAWA Hiroyuki wrote:
> Thank you, very helpful. but some nitpicks.
> 
> 
> On Wed, 8 Apr 2009 12:48:17 +0530
> Bharata B Rao <bharata@linux.vnet.ibm.com> wrote:
> 
> > memcg: Fix documentation.
> > 
> > The description about various statistics from memory.stat is not accurate
> > and confusing at times.
> > 
> > +active_anon	- # of bytes of anonymous memory on active lru list.
>                                 anonymous memory + shared memory(tmpfs) + SwapCache.

Since these stats are for user consumption, I think we need not explicitly
mention the inclusion of tmpfs pages here. What do you think ?

Regards,
Bharata.

Re: [PATCH] memcg: Fix documentation

[KAMEZAWA Hiroyuki]

On Wed, 8 Apr 2009 15:04:01 +0530
Bharata B Rao <bharata@linux.vnet.ibm.com> wrote:

> On Wed, Apr 08, 2009 at 04:25:28PM +0900, KAMEZAWA Hiroyuki wrote:
> > Thank you, very helpful. but some nitpicks.
> > 
> > 
> > On Wed, 8 Apr 2009 12:48:17 +0530
> > Bharata B Rao <bharata@linux.vnet.ibm.com> wrote:
> > 
> > > memcg: Fix documentation.
> > > 
> > > The description about various statistics from memory.stat is not accurate
> > > and confusing at times.
> > > 
> > > +active_anon	- # of bytes of anonymous memory on active lru list.
> >                                 anonymous memory + shared memory(tmpfs) + SwapCache.
> 
> Since these stats are for user consumption, I think we need not explicitly
> mention the inclusion of tmpfs pages here. What do you think ?
> 
Maybe it's better.
Anyway, this information is the same to what /proc/meminfo shows.

Thanks,
-Kame