Documentation/controllers/memory.txt

   1 <<<<<<< HEAD:Documentation/controllers/memory.txt
   2 Memory Controller
   3 =======
   4 Memory Resource Controller
   5
   6 NOTE: The Memory Resource Controller has been generically been referred
   7 to as the memory controller in this document. Do not confuse memory controller
   8 used here with the memory controller that is used in hardware.
   9 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
  10
  11 Salient features
  12
  13 a. Enable control of both RSS (mapped) and Page Cache (unmapped) pages
  14 b. The infrastructure allows easy addition of other types of memory to control
  15 c. Provides *zero overhead* for non memory controller users
  16 d. Provides a double LRU: global memory pressure causes reclaim from the
  17    global LRU; a cgroup on hitting a limit, reclaims from the per
  18    cgroup LRU
  19
  20 NOTE: Swap Cache (unmapped) is not accounted now.
  21
  22 Benefits and Purpose of the memory controller
  23
  24 The memory controller isolates the memory behaviour of a group of tasks
  25 from the rest of the system. The article on LWN [12] mentions some probable
  26 uses of the memory controller. The memory controller can be used to
  27
  28 a. Isolate an application or a group of applications
  29    Memory hungry applications can be isolated and limited to a smaller
  30    amount of memory.
  31 b. Create a cgroup with limited amount of memory, this can be used
  32    as a good alternative to booting with mem=XXXX.
  33 c. Virtualization solutions can control the amount of memory they want
  34    to assign to a virtual machine instance.
  35 d. A CD/DVD burner could control the amount of memory used by the
  36    rest of the system to ensure that burning does not fail due to lack
  37    of available memory.
  38 e. There are several other use cases, find one or use the controller just
  39    for fun (to learn and hack on the VM subsystem).
  40
  41 1. History
  42
  43 The memory controller has a long history. A request for comments for the memory
  44 controller was posted by Balbir Singh [1]. At the time the RFC was posted
  45 there were several implementations for memory control. The goal of the
  46 RFC was to build consensus and agreement for the minimal features required
  47 for memory control. The first RSS controller was posted by Balbir Singh[2]
  48 in Feb 2007. Pavel Emelianov [3][4][5] has since posted three versions of the
  49 RSS controller. At OLS, at the resource management BoF, everyone suggested
  50 that we handle both page cache and RSS together. Another request was raised
  51 to allow user space handling of OOM. The current memory controller is
  52 at version 6; it combines both mapped (RSS) and unmapped Page
  53 Cache Control [11].
  54
  55 2. Memory Control
  56
  57 Memory is a unique resource in the sense that it is present in a limited
  58 amount. If a task requires a lot of CPU processing, the task can spread
  59 its processing over a period of hours, days, months or years, but with
  60 memory, the same physical memory needs to be reused to accomplish the task.
  61
  62 The memory controller implementation has been divided into phases. These
  63 are:
  64
  65 1. Memory controller
  66 2. mlock(2) controller
  67 3. Kernel user memory accounting and slab control
  68 4. user mappings length controller
  69
  70 The memory controller is the first controller developed.
  71
  72 2.1. Design
  73
  74 The core of the design is a counter called the res_counter. The res_counter
  75 tracks the current memory usage and limit of the group of processes associated
  76 with the controller. Each cgroup has a memory controller specific data
  77 structure (mem_cgroup) associated with it.
  78
  79 2.2. Accounting
  80
  81                 +--------------------+
  82                 |  mem_cgroup     |
  83                 |  (res_counter)     |
  84                 +--------------------+
  85                  /            ^      \
  86                 /             |       \
  87            +---------------+  |        +---------------+
  88            | mm_struct     |  |....    | mm_struct     |
  89            |               |  |        |               |
  90            +---------------+  |        +---------------+
  91                               |
  92                               + --------------+
  93                                               |
  94            +---------------+           +------+--------+
  95            | page          +---------->  page_cgroup|
  96            |               |           |               |
  97            +---------------+           +---------------+
  98
  99              (Figure 1: Hierarchy of Accounting)
 100
 101
 102 Figure 1 shows the important aspects of the controller
 103
 104 1. Accounting happens per cgroup
 105 2. Each mm_struct knows about which cgroup it belongs to
 106 3. Each page has a pointer to the page_cgroup, which in turn knows the
 107    cgroup it belongs to
 108
 109 The accounting is done as follows: mem_cgroup_charge() is invoked to setup
 110 the necessary data structures and check if the cgroup that is being charged
 111 is over its limit. If it is then reclaim is invoked on the cgroup.
 112 More details can be found in the reclaim section of this document.
 113 If everything goes well, a page meta-data-structure called page_cgroup is
 114 allocated and associated with the page.  This routine also adds the page to
 115 the per cgroup LRU.
 116
 117 2.2.1 Accounting details
 118
 119 All mapped pages (RSS) and unmapped user pages (Page Cache) are accounted.
 120 RSS pages are accounted at the time of page_add_*_rmap() unless they've already
 121 been accounted for earlier. A file page will be accounted for as Page Cache;
 122 it's mapped into the page tables of a process, duplicate accounting is carefully
 123 avoided. Page Cache pages are accounted at the time of add_to_page_cache().
 124 The corresponding routines that remove a page from the page tables or removes
 125 a page from Page Cache is used to decrement the accounting counters of the
 126 cgroup.
 127
 128 2.3 Shared Page Accounting
 129
 130 Shared pages are accounted on the basis of the first touch approach. The
 131 cgroup that first touches a page is accounted for the page. The principle
 132 behind this approach is that a cgroup that aggressively uses a shared
 133 page will eventually get charged for it (once it is uncharged from
 134 the cgroup that brought it in -- this will happen on memory pressure).
 135
 136 2.4 Reclaim
 137
 138 Each cgroup maintains a per cgroup LRU that consists of an active
 139 and inactive list. When a cgroup goes over its limit, we first try
 140 to reclaim memory from the cgroup so as to make space for the new
 141 pages that the cgroup has touched. If the reclaim is unsuccessful,
 142 an OOM routine is invoked to select and kill the bulkiest task in the
 143 cgroup.
 144
 145 The reclaim algorithm has not been modified for cgroups, except that
 146 pages that are selected for reclaiming come from the per cgroup LRU
 147 list.
 148
 149 2. Locking
 150
 151 The memory controller uses the following hierarchy
 152
 153 1. zone->lru_lock is used for selecting pages to be isolated
 154 2. mem->per_zone->lru_lock protects the per cgroup LRU (per zone)
 155 3. lock_page_cgroup() is used to protect page->page_cgroup
 156
 157 3. User Interface
 158
 159 0. Configuration
 160
 161 a. Enable CONFIG_CGROUPS
 162 b. Enable CONFIG_RESOURCE_COUNTERS
 163 <<<<<<< HEAD:Documentation/controllers/memory.txt
 164 c. Enable CONFIG_CGROUP_MEM_CONT
 165 =======
 166 c. Enable CONFIG_CGROUP_MEM_RES_CTLR
 167 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 168
 169 1. Prepare the cgroups
 170 # mkdir -p /cgroups
 171 # mount -t cgroup none /cgroups -o memory
 172
 173 2. Make the new group and move bash into it
 174 # mkdir /cgroups/0
 175 # echo $$ >  /cgroups/0/tasks
 176
 177 Since now we're in the 0 cgroup,
 178 We can alter the memory limit:
 179 <<<<<<< HEAD:Documentation/controllers/memory.txt
 180 # echo -n 4M > /cgroups/0/memory.limit_in_bytes
 181 =======
 182 # echo 4M > /cgroups/0/memory.limit_in_bytes
 183 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 184
 185 NOTE: We can use a suffix (k, K, m, M, g or G) to indicate values in kilo,
 186 mega or gigabytes.
 187
 188 # cat /cgroups/0/memory.limit_in_bytes
 189 <<<<<<< HEAD:Documentation/controllers/memory.txt
 190 4194304 Bytes
 191 =======
 192 4194304
 193 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 194
 195 NOTE: The interface has now changed to display the usage in bytes
 196 instead of pages
 197
 198 We can check the usage:
 199 # cat /cgroups/0/memory.usage_in_bytes
 200 <<<<<<< HEAD:Documentation/controllers/memory.txt
 201 1216512 Bytes
 202 =======
 203 1216512
 204 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 205
 206 A successful write to this file does not guarantee a successful set of
 207 this limit to the value written into the file.  This can be due to a
 208 number of factors, such as rounding up to page boundaries or the total
 209 availability of memory on the system.  The user is required to re-read
 210 this file after a write to guarantee the value committed by the kernel.
 211
 212 <<<<<<< HEAD:Documentation/controllers/memory.txt
 213 # echo -n 1 > memory.limit_in_bytes
 214 =======
 215 # echo 1 > memory.limit_in_bytes
 216 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 217 # cat memory.limit_in_bytes
 218 <<<<<<< HEAD:Documentation/controllers/memory.txt
 219 4096 Bytes
 220 =======
 221 4096
 222 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 223
 224 The memory.failcnt field gives the number of times that the cgroup limit was
 225 exceeded.
 226
 227 The memory.stat file gives accounting information. Now, the number of
 228 caches, RSS and Active pages/Inactive pages are shown.
 229
 230 The memory.force_empty gives an interface to drop *all* charges by force.
 231
 232 <<<<<<< HEAD:Documentation/controllers/memory.txt
 233 # echo -n 1 > memory.force_empty
 234 =======
 235 # echo 1 > memory.force_empty
 236 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 237
 238 will drop all charges in cgroup. Currently, this is maintained for test.
 239
 240 4. Testing
 241
 242 Balbir posted lmbench, AIM9, LTP and vmmstress results [10] and [11].
 243 Apart from that v6 has been tested with several applications and regular
 244 daily use. The controller has also been tested on the PPC64, x86_64 and
 245 UML platforms.
 246
 247 4.1 Troubleshooting
 248
 249 Sometimes a user might find that the application under a cgroup is
 250 terminated. There are several causes for this:
 251
 252 1. The cgroup limit is too low (just too low to do anything useful)
 253 2. The user is using anonymous memory and swap is turned off or too low
 254
 255 A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of
 256 some of the pages cached in the cgroup (page cache pages).
 257
 258 4.2 Task migration
 259
 260 When a task migrates from one cgroup to another, it's charge is not
 261 carried forward. The pages allocated from the original cgroup still
 262 remain charged to it, the charge is dropped when the page is freed or
 263 reclaimed.
 264
 265 4.3 Removing a cgroup
 266
 267 A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a
 268 cgroup might have some charge associated with it, even though all
 269 tasks have migrated away from it. Such charges are automatically dropped at
 270 rmdir() if there are no tasks.
 271
 272 <<<<<<< HEAD:Documentation/controllers/memory.txt
 273 4.4 Choosing what to account  -- Page Cache (unmapped) vs RSS (mapped)?
 274
 275 The type of memory accounted by the cgroup can be limited to just
 276 mapped pages by writing "1" to memory.control_type field
 277
 278 echo -n 1 > memory.control_type
 279
 280 =======
 281 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 282 5. TODO
 283
 284 1. Add support for accounting huge pages (as a separate controller)
 285 2. Make per-cgroup scanner reclaim not-shared pages first
 286 3. Teach controller to account for shared-pages
 287 4. Start reclamation when the limit is lowered
 288 5. Start reclamation in the background when the limit is
 289    not yet hit but the usage is getting closer
 290
 291 Summary
 292
 293 Overall, the memory controller has been a stable controller and has been
 294 commented and discussed quite extensively in the community.
 295
 296 References
 297
 298 1. Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/
 299 2. Singh, Balbir. Memory Controller (RSS Control),
 300    http://lwn.net/Articles/222762/
 301 3. Emelianov, Pavel. Resource controllers based on process cgroups
 302    http://lkml.org/lkml/2007/3/6/198
 303 4. Emelianov, Pavel. RSS controller based on process cgroups (v2)
 304 <<<<<<< HEAD:Documentation/controllers/memory.txt
 305    http://lkml.org/lkml/2007/4/9/74
 306 =======
 307    http://lkml.org/lkml/2007/4/9/78
 308 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 309 5. Emelianov, Pavel. RSS controller based on process cgroups (v3)
 310    http://lkml.org/lkml/2007/5/30/244
 311 6. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/
 312 7. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control
 313    subsystem (v3), http://lwn.net/Articles/235534/
 314 <<<<<<< HEAD:Documentation/controllers/memory.txt
 315 8. Singh, Balbir. RSS controller V2 test results (lmbench),
 316 =======
 317 8. Singh, Balbir. RSS controller v2 test results (lmbench),
 318 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 319    http://lkml.org/lkml/2007/5/17/232
 320 <<<<<<< HEAD:Documentation/controllers/memory.txt
 321 9. Singh, Balbir. RSS controller V2 AIM9 results
 322 =======
 323 9. Singh, Balbir. RSS controller v2 AIM9 results
 324 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 325    http://lkml.org/lkml/2007/5/18/1
 326 <<<<<<< HEAD:Documentation/controllers/memory.txt
 327 10. Singh, Balbir. Memory controller v6 results,
 328 =======
 329 10. Singh, Balbir. Memory controller v6 test results,
 330 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 331     http://lkml.org/lkml/2007/8/19/36
 332 <<<<<<< HEAD:Documentation/controllers/memory.txt
 333 11. Singh, Balbir. Memory controller v6, http://lkml.org/lkml/2007/8/17/69
 334 =======
 335 11. Singh, Balbir. Memory controller introduction (v6),
 336     http://lkml.org/lkml/2007/8/17/69
 337 >>>>>>> 264e3e889d86e552b4191d69bb60f4f3b383135a:Documentation/controllers/memory.txt
 338 12. Corbet, Jonathan, Controlling memory use in cgroups,
 339     http://lwn.net/Articles/243795/