Documentation/admin-guide/cgroup-v1/memcg_test.rst

   1 =====================================================
   2 Memory Resource Controller(Memcg) Implementation Memo
   3 =====================================================
   4
   5 Last Updated: 2010/2
   6
   7 Base Kernel Version: based on 2.6.33-rc7-mm(candidate for 34).
   8
   9 Because VM is getting complex (one of reasons is memcg...), memcg's behavior
  10 is complex. This is a document for memcg's internal behavior.
  11 Please note that implementation details can be changed.
  12
  13 (*) Topics on API should be in Documentation/admin-guide/cgroup-v1/memory.rst)
  14
  15 0. How to record usage ?
  16 ========================
  17
  18    2 objects are used.
  19
  20    page_cgroup ....an object per page.
  21
  22         Allocated at boot or memory hotplug. Freed at memory hot removal.
  23
  24    swap_cgroup ... an entry per swp_entry.
  25
  26         Allocated at swapon(). Freed at swapoff().
  27
  28    The page_cgroup has USED bit and double count against a page_cgroup never
  29    occurs. swap_cgroup is used only when a charged page is swapped-out.
  30
  31 1. Charge
  32 =========
  33
  34    a page/swp_entry may be charged (usage += PAGE_SIZE) at
  35
  36         mem_cgroup_try_charge()
  37
  38 2. Uncharge
  39 ===========
  40
  41   a page/swp_entry may be uncharged (usage -= PAGE_SIZE) by
  42
  43         mem_cgroup_uncharge()
  44           Called when a page's refcount goes down to 0.
  45
  46         mem_cgroup_uncharge_swap()
  47           Called when swp_entry's refcnt goes down to 0. A charge against swap
  48           disappears.
  49
  50 3. charge-commit-cancel
  51 =======================
  52
  53         Memcg pages are charged in two steps:
  54
  55                 - mem_cgroup_try_charge()
  56                 - mem_cgroup_commit_charge() or mem_cgroup_cancel_charge()
  57
  58         At try_charge(), there are no flags to say "this page is charged".
  59         at this point, usage += PAGE_SIZE.
  60
  61         At commit(), the page is associated with the memcg.
  62
  63         At cancel(), simply usage -= PAGE_SIZE.
  64
  65 Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y.
  66
  67 4. Anonymous
  68 ============
  69
  70         Anonymous page is newly allocated at
  71                   - page fault into MAP_ANONYMOUS mapping.
  72                   - Copy-On-Write.
  73
  74         4.1 Swap-in.
  75         At swap-in, the page is taken from swap-cache. There are 2 cases.
  76
  77         (a) If the SwapCache is newly allocated and read, it has no charges.
  78         (b) If the SwapCache has been mapped by processes, it has been
  79             charged already.
  80
  81         4.2 Swap-out.
  82         At swap-out, typical state transition is below.
  83
  84         (a) add to swap cache. (marked as SwapCache)
  85             swp_entry's refcnt += 1.
  86         (b) fully unmapped.
  87             swp_entry's refcnt += # of ptes.
  88         (c) write back to swap.
  89         (d) delete from swap cache. (remove from SwapCache)
  90             swp_entry's refcnt -= 1.
  91
  92
  93         Finally, at task exit,
  94         (e) zap_pte() is called and swp_entry's refcnt -=1 -> 0.
  95
  96 5. Page Cache
  97 =============
  98
  99         Page Cache is charged at
 100         - add_to_page_cache_locked().
 101
 102         The logic is very clear. (About migration, see below)
 103
 104         Note:
 105           __remove_from_page_cache() is called by remove_from_page_cache()
 106           and __remove_mapping().
 107
 108 6. Shmem(tmpfs) Page Cache
 109 ===========================
 110
 111         The best way to understand shmem's page state transition is to read
 112         mm/shmem.c.
 113
 114         But brief explanation of the behavior of memcg around shmem will be
 115         helpful to understand the logic.
 116
 117         Shmem's page (just leaf page, not direct/indirect block) can be on
 118
 119                 - radix-tree of shmem's inode.
 120                 - SwapCache.
 121                 - Both on radix-tree and SwapCache. This happens at swap-in
 122                   and swap-out,
 123
 124         It's charged when...
 125
 126         - A new page is added to shmem's radix-tree.
 127         - A swp page is read. (move a charge from swap_cgroup to page_cgroup)
 128
 129 7. Page Migration
 130 =================
 131
 132         mem_cgroup_migrate()
 133
 134 8. LRU
 135 ======
 136         Each memcg has its own vector of LRUs (inactive anon, active anon,
 137         inactive file, active file, unevictable) of pages from each node,
 138         each LRU handled under a single lru_lock for that memcg and node.
 139
 140 9. Typical Tests.
 141 =================
 142
 143  Tests for racy cases.
 144
 145 9.1 Small limit to memcg.
 146 -------------------------
 147
 148         When you do test to do racy case, it's good test to set memcg's limit
 149         to be very small rather than GB. Many races found in the test under
 150         xKB or xxMB limits.
 151
 152         (Memory behavior under GB and Memory behavior under MB shows very
 153         different situation.)
 154
 155 9.2 Shmem
 156 ---------
 157
 158         Historically, memcg's shmem handling was poor and we saw some amount
 159         of troubles here. This is because shmem is page-cache but can be
 160         SwapCache. Test with shmem/tmpfs is always good test.
 161
 162 9.3 Migration
 163 -------------
 164
 165         For NUMA, migration is an another special case. To do easy test, cpuset
 166         is useful. Following is a sample script to do migration::
 167
 168                 mount -t cgroup -o cpuset none /opt/cpuset
 169
 170                 mkdir /opt/cpuset/01
 171                 echo 1 > /opt/cpuset/01/cpuset.cpus
 172                 echo 0 > /opt/cpuset/01/cpuset.mems
 173                 echo 1 > /opt/cpuset/01/cpuset.memory_migrate
 174                 mkdir /opt/cpuset/02
 175                 echo 1 > /opt/cpuset/02/cpuset.cpus
 176                 echo 1 > /opt/cpuset/02/cpuset.mems
 177                 echo 1 > /opt/cpuset/02/cpuset.memory_migrate
 178
 179         In above set, when you moves a task from 01 to 02, page migration to
 180         node 0 to node 1 will occur. Following is a script to migrate all
 181         under cpuset.::
 182
 183                 --
 184                 move_task()
 185                 {
 186                 for pid in $1
 187                 do
 188                         /bin/echo $pid >$2/tasks 2>/dev/null
 189                         echo -n $pid
 190                         echo -n " "
 191                 done
 192                 echo END
 193                 }
 194
 195                 G1_TASK=`cat ${G1}/tasks`
 196                 G2_TASK=`cat ${G2}/tasks`
 197                 move_task "${G1_TASK}" ${G2} &
 198                 --
 199
 200 9.4 Memory hotplug
 201 ------------------
 202
 203         memory hotplug test is one of good test.
 204
 205         to offline memory, do following::
 206
 207                 # echo offline > /sys/devices/system/memory/memoryXXX/state
 208
 209         (XXX is the place of memory)
 210
 211         This is an easy way to test page migration, too.
 212
 213 9.5 nested cgroups
 214 ------------------
 215
 216         Use tests like the following for testing nested cgroups::
 217
 218                 mkdir /opt/cgroup/01/child_a
 219                 mkdir /opt/cgroup/01/child_b
 220
 221                 set limit to 01.
 222                 add limit to 01/child_b
 223                 run jobs under child_a and child_b
 224
 225         create/delete following groups at random while jobs are running::
 226
 227                 /opt/cgroup/01/child_a/child_aa
 228                 /opt/cgroup/01/child_b/child_bb
 229                 /opt/cgroup/01/child_c
 230
 231         running new jobs in new group is also good.
 232
 233 9.6 Mount with other subsystems
 234 -------------------------------
 235
 236         Mounting with other subsystems is a good test because there is a
 237         race and lock dependency with other cgroup subsystems.
 238
 239         example::
 240
 241                 # mount -t cgroup none /cgroup -o cpuset,memory,cpu,devices
 242
 243         and do task move, mkdir, rmdir etc...under this.
 244
 245 9.7 swapoff
 246 -----------
 247
 248         Besides management of swap is one of complicated parts of memcg,
 249         call path of swap-in at swapoff is not same as usual swap-in path..
 250         It's worth to be tested explicitly.
 251
 252         For example, test like following is good:
 253
 254         (Shell-A)::
 255
 256                 # mount -t cgroup none /cgroup -o memory
 257                 # mkdir /cgroup/test
 258                 # echo 40M > /cgroup/test/memory.limit_in_bytes
 259                 # echo 0 > /cgroup/test/tasks
 260
 261         Run malloc(100M) program under this. You'll see 60M of swaps.
 262
 263         (Shell-B)::
 264
 265                 # move all tasks in /cgroup/test to /cgroup
 266                 # /sbin/swapoff -a
 267                 # rmdir /cgroup/test
 268                 # kill malloc task.
 269
 270         Of course, tmpfs v.s. swapoff test should be tested, too.
 271
 272 9.8 OOM-Killer
 273 --------------
 274
 275         Out-of-memory caused by memcg's limit will kill tasks under
 276         the memcg. When hierarchy is used, a task under hierarchy
 277         will be killed by the kernel.
 278
 279         In this case, panic_on_oom shouldn't be invoked and tasks
 280         in other groups shouldn't be killed.
 281
 282         It's not difficult to cause OOM under memcg as following.
 283
 284         Case A) when you can swapoff::
 285
 286                 #swapoff -a
 287                 #echo 50M > /memory.limit_in_bytes
 288
 289         run 51M of malloc
 290
 291         Case B) when you use mem+swap limitation::
 292
 293                 #echo 50M > memory.limit_in_bytes
 294                 #echo 50M > memory.memsw.limit_in_bytes
 295
 296         run 51M of malloc
 297
 298 9.9 Move charges at task migration
 299 ----------------------------------
 300
 301         Charges associated with a task can be moved along with task migration.
 302
 303         (Shell-A)::
 304
 305                 #mkdir /cgroup/A
 306                 #echo $$ >/cgroup/A/tasks
 307
 308         run some programs which uses some amount of memory in /cgroup/A.
 309
 310         (Shell-B)::
 311
 312                 #mkdir /cgroup/B
 313                 #echo 1 >/cgroup/B/memory.move_charge_at_immigrate
 314                 #echo "pid of the program running in group A" >/cgroup/B/tasks
 315
 316         You can see charges have been moved by reading ``*.usage_in_bytes`` or
 317         memory.stat of both A and B.
 318
 319         See 8.2 of Documentation/admin-guide/cgroup-v1/memory.rst to see what value should
 320         be written to move_charge_at_immigrate.
 321
 322 9.10 Memory thresholds
 323 ----------------------
 324
 325         Memory controller implements memory thresholds using cgroups notification
 326         API. You can use tools/cgroup/cgroup_event_listener.c to test it.
 327
 328         (Shell-A) Create cgroup and run event listener::
 329
 330                 # mkdir /cgroup/A
 331                 # ./cgroup_event_listener /cgroup/A/memory.usage_in_bytes 5M
 332
 333         (Shell-B) Add task to cgroup and try to allocate and free memory::
 334
 335                 # echo $$ >/cgroup/A/tasks
 336                 # a="$(dd if=/dev/zero bs=1M count=10)"
 337                 # a=
 338
 339         You will see message from cgroup_event_listener every time you cross
 340         the thresholds.
 341
 342         Use /cgroup/A/memory.memsw.usage_in_bytes to test memsw thresholds.
 343
 344         It's good idea to test root cgroup as well.