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 private LRU. Now, its handling is under global
 137         VM's control (means that it's handled under global pgdat->lru_lock).
 138         Almost all routines around memcg's LRU is called by global LRU's
 139         list management functions under pgdat->lru_lock.
 140
 141         A special function is mem_cgroup_isolate_pages(). This scans
 142         memcg's private LRU and call __isolate_lru_page() to extract a page
 143         from LRU.
 144
 145         (By __isolate_lru_page(), the page is removed from both of global and
 146         private LRU.)
 147
 148
 149 9. Typical Tests.
 150 =================
 151
 152  Tests for racy cases.
 153
 154 9.1 Small limit to memcg.
 155 -------------------------
 156
 157         When you do test to do racy case, it's good test to set memcg's limit
 158         to be very small rather than GB. Many races found in the test under
 159         xKB or xxMB limits.
 160
 161         (Memory behavior under GB and Memory behavior under MB shows very
 162         different situation.)
 163
 164 9.2 Shmem
 165 ---------
 166
 167         Historically, memcg's shmem handling was poor and we saw some amount
 168         of troubles here. This is because shmem is page-cache but can be
 169         SwapCache. Test with shmem/tmpfs is always good test.
 170
 171 9.3 Migration
 172 -------------
 173
 174         For NUMA, migration is an another special case. To do easy test, cpuset
 175         is useful. Following is a sample script to do migration::
 176
 177                 mount -t cgroup -o cpuset none /opt/cpuset
 178
 179                 mkdir /opt/cpuset/01
 180                 echo 1 > /opt/cpuset/01/cpuset.cpus
 181                 echo 0 > /opt/cpuset/01/cpuset.mems
 182                 echo 1 > /opt/cpuset/01/cpuset.memory_migrate
 183                 mkdir /opt/cpuset/02
 184                 echo 1 > /opt/cpuset/02/cpuset.cpus
 185                 echo 1 > /opt/cpuset/02/cpuset.mems
 186                 echo 1 > /opt/cpuset/02/cpuset.memory_migrate
 187
 188         In above set, when you moves a task from 01 to 02, page migration to
 189         node 0 to node 1 will occur. Following is a script to migrate all
 190         under cpuset.::
 191
 192                 --
 193                 move_task()
 194                 {
 195                 for pid in $1
 196                 do
 197                         /bin/echo $pid >$2/tasks 2>/dev/null
 198                         echo -n $pid
 199                         echo -n " "
 200                 done
 201                 echo END
 202                 }
 203
 204                 G1_TASK=`cat ${G1}/tasks`
 205                 G2_TASK=`cat ${G2}/tasks`
 206                 move_task "${G1_TASK}" ${G2} &
 207                 --
 208
 209 9.4 Memory hotplug
 210 ------------------
 211
 212         memory hotplug test is one of good test.
 213
 214         to offline memory, do following::
 215
 216                 # echo offline > /sys/devices/system/memory/memoryXXX/state
 217
 218         (XXX is the place of memory)
 219
 220         This is an easy way to test page migration, too.
 221
 222 9.5 mkdir/rmdir
 223 ---------------
 224
 225         When using hierarchy, mkdir/rmdir test should be done.
 226         Use tests like the following::
 227
 228                 echo 1 >/opt/cgroup/01/memory/use_hierarchy
 229                 mkdir /opt/cgroup/01/child_a
 230                 mkdir /opt/cgroup/01/child_b
 231
 232                 set limit to 01.
 233                 add limit to 01/child_b
 234                 run jobs under child_a and child_b
 235
 236         create/delete following groups at random while jobs are running::
 237
 238                 /opt/cgroup/01/child_a/child_aa
 239                 /opt/cgroup/01/child_b/child_bb
 240                 /opt/cgroup/01/child_c
 241
 242         running new jobs in new group is also good.
 243
 244 9.6 Mount with other subsystems
 245 -------------------------------
 246
 247         Mounting with other subsystems is a good test because there is a
 248         race and lock dependency with other cgroup subsystems.
 249
 250         example::
 251
 252                 # mount -t cgroup none /cgroup -o cpuset,memory,cpu,devices
 253
 254         and do task move, mkdir, rmdir etc...under this.
 255
 256 9.7 swapoff
 257 -----------
 258
 259         Besides management of swap is one of complicated parts of memcg,
 260         call path of swap-in at swapoff is not same as usual swap-in path..
 261         It's worth to be tested explicitly.
 262
 263         For example, test like following is good:
 264
 265         (Shell-A)::
 266
 267                 # mount -t cgroup none /cgroup -o memory
 268                 # mkdir /cgroup/test
 269                 # echo 40M > /cgroup/test/memory.limit_in_bytes
 270                 # echo 0 > /cgroup/test/tasks
 271
 272         Run malloc(100M) program under this. You'll see 60M of swaps.
 273
 274         (Shell-B)::
 275
 276                 # move all tasks in /cgroup/test to /cgroup
 277                 # /sbin/swapoff -a
 278                 # rmdir /cgroup/test
 279                 # kill malloc task.
 280
 281         Of course, tmpfs v.s. swapoff test should be tested, too.
 282
 283 9.8 OOM-Killer
 284 --------------
 285
 286         Out-of-memory caused by memcg's limit will kill tasks under
 287         the memcg. When hierarchy is used, a task under hierarchy
 288         will be killed by the kernel.
 289
 290         In this case, panic_on_oom shouldn't be invoked and tasks
 291         in other groups shouldn't be killed.
 292
 293         It's not difficult to cause OOM under memcg as following.
 294
 295         Case A) when you can swapoff::
 296
 297                 #swapoff -a
 298                 #echo 50M > /memory.limit_in_bytes
 299
 300         run 51M of malloc
 301
 302         Case B) when you use mem+swap limitation::
 303
 304                 #echo 50M > memory.limit_in_bytes
 305                 #echo 50M > memory.memsw.limit_in_bytes
 306
 307         run 51M of malloc
 308
 309 9.9 Move charges at task migration
 310 ----------------------------------
 311
 312         Charges associated with a task can be moved along with task migration.
 313
 314         (Shell-A)::
 315
 316                 #mkdir /cgroup/A
 317                 #echo $$ >/cgroup/A/tasks
 318
 319         run some programs which uses some amount of memory in /cgroup/A.
 320
 321         (Shell-B)::
 322
 323                 #mkdir /cgroup/B
 324                 #echo 1 >/cgroup/B/memory.move_charge_at_immigrate
 325                 #echo "pid of the program running in group A" >/cgroup/B/tasks
 326
 327         You can see charges have been moved by reading ``*.usage_in_bytes`` or
 328         memory.stat of both A and B.
 329
 330         See 8.2 of Documentation/admin-guide/cgroup-v1/memory.rst to see what value should
 331         be written to move_charge_at_immigrate.
 332
 333 9.10 Memory thresholds
 334 ----------------------
 335
 336         Memory controller implements memory thresholds using cgroups notification
 337         API. You can use tools/cgroup/cgroup_event_listener.c to test it.
 338
 339         (Shell-A) Create cgroup and run event listener::
 340
 341                 # mkdir /cgroup/A
 342                 # ./cgroup_event_listener /cgroup/A/memory.usage_in_bytes 5M
 343
 344         (Shell-B) Add task to cgroup and try to allocate and free memory::
 345
 346                 # echo $$ >/cgroup/A/tasks
 347                 # a="$(dd if=/dev/zero bs=1M count=10)"
 348                 # a=
 349
 350         You will see message from cgroup_event_listener every time you cross
 351         the thresholds.
 352
 353         Use /cgroup/A/memory.memsw.usage_in_bytes to test memsw thresholds.
 354
 355         It's good idea to test root cgroup as well.