3 files changed, 71 insertions, 29 deletions

diff --git a/Documentation/cgroups/cpuacct.txt b/Documentation/cgroups/cpuacct.txt
index bb775fbe43d7..8b930946c52a 100644
--- a/Documentation/cgroups/cpuacct.txt
+++ b/Documentation/cgroups/cpuacct.txt
@@ -30,3 +30,21 @@ The above steps create a new group g1 and move the current shell
 process (bash) into it. CPU time consumed by this bash and its children
 can be obtained from g1/cpuacct.usage and the same is accumulated in
 /cgroups/cpuacct.usage also.
+
+cpuacct.stat file lists a few statistics which further divide the
+CPU time obtained by the cgroup into user and system times. Currently
+the following statistics are supported:
+
+user: Time spent by tasks of the cgroup in user mode.
+system: Time spent by tasks of the cgroup in kernel mode.
+
+user and system are in USER_HZ unit.
+
+cpuacct controller uses percpu_counter interface to collect user and
+system times. This has two side effects:
+
+- It is theoretically possible to see wrong values for user and system times.
+  This is because percpu_counter_read() on 32bit systems isn't safe
+  against concurrent writes.
+- It is possible to see slightly outdated values for user and system times
+  due to the batch processing nature of percpu_counter.
diff --git a/Documentation/cgroups/memory.txt b/Documentation/cgroups/memory.txt
index a98a7fe7aabb..1a608877b14e 100644
--- a/Documentation/cgroups/memory.txt
+++ b/Documentation/cgroups/memory.txt
@@ -6,15 +6,14 @@ used here with the memory controller that is used in hardware.
 
 Salient features
 
-a. Enable control of both RSS (mapped) and Page Cache (unmapped) pages
+a. Enable control of Anonymous, Page Cache (mapped and unmapped) and
+   Swap Cache memory 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,44 @@ 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 internal 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 and swap cache 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 and  swap cache memory on active
+                  lru list.
+inactive_anon   - # of bytes of anonymous memory and swap cache 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 internal 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 and swap cache 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. Per-cgroup rss
+        accounting is not done yet.
 
 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.
diff --git a/Documentation/cgroups/resource_counter.txt b/Documentation/cgroups/resource_counter.txt
index f196ac1d7d25..95b24d766eab 100644
--- a/Documentation/cgroups/resource_counter.txt
+++ b/Documentation/cgroups/resource_counter.txt
@@ -47,13 +47,18 @@ to work with it.
 
 2. Basic accounting routines
 
- a. void res_counter_init(struct res_counter *rc)
+ a. void res_counter_init(struct res_counter *rc,
+                                struct res_counter *rc_parent)
 
         Initializes the resource counter. As usual, should be the first
         routine called for a new counter.
 
- b. int res_counter_charge[_locked]
-                        (struct res_counter *rc, unsigned long val)
+        The struct res_counter *parent can be used to define a hierarchical
+        child -> parent relationship directly in the res_counter structure,
+        NULL can be used to define no relationship.
+
+ c. int res_counter_charge(struct res_counter *rc, unsigned long val,
+                                struct res_counter **limit_fail_at)
 
         When a resource is about to be allocated it has to be accounted
         with the appropriate resource counter (controller should determine
@@ -67,15 +72,25 @@ to work with it.
           * if the charging is performed first, then it should be uncharged
             on error path (if the one is called).
 
- c. void res_counter_uncharge[_locked]
+        If the charging fails and a hierarchical dependency exists, the
+        limit_fail_at parameter is set to the particular res_counter element
+        where the charging failed.
+
+ d. int res_counter_charge_locked
+                        (struct res_counter *rc, unsigned long val)
+
+        The same as res_counter_charge(), but it must not acquire/release the
+        res_counter->lock internally (it must be called with res_counter->lock
+        held).
+
+ e. void res_counter_uncharge[_locked]
                         (struct res_counter *rc, unsigned long val)
 
         When a resource is released (freed) it should be de-accounted
         from the resource counter it was accounted to.  This is called
         "uncharging".
 
-    The _locked routines imply that the res_counter->lock is taken.
-
+        The _locked routines imply that the res_counter->lock is taken.
 
  2.1 Other accounting routines