Documentation/ckrm/mem_rc.design

   1 0. Lifecycle of a LRU Page:
   2 ----------------------------
   3 These are the events in a page's lifecycle:
   4    - allocation of the page
   5      there are multiple high level page alloc functions; __alloc_pages()
   6          is the lowest level function that does the real allocation.
   7    - get into LRU list (active list or inactive list)
   8    - get out of LRU list
   9    - freeing the page
  10      there are multiple high level page free functions; free_pages_bulk()
  11          is the lowest level function that does the real free.
  12
  13 When the memory subsystem runs low on LRU pages, pages are reclaimed by
  14     - moving pages from active list to inactive list (refill_inactive_zone())
  15         - freeing pages from the inactive list (shrink_zone)
  16 depending on the recent usage of the page(approximately).
  17
  18 1. Introduction
  19 ---------------
  20 Memory resource controller controls the number of lru physical pages
  21 (active and inactive list) a class uses. It does not restrict any
  22 other physical pages (slabs etc.,)
  23
  24 For simplicity, this document will always refer lru physical pages as
  25 physical pages or simply pages.
  26
  27 There are two parameters(that are set by the user) that affect the number
  28 of pages a class is allowed to have in active/inactive list.
  29 They are
  30   - guarantee - specifies the number of pages a class is
  31         guaranteed to get. In other words, if a class is using less than
  32         'guarantee' number of pages, its pages will not be freed when the
  33         memory subsystem tries to free some pages.
  34   - limit - specifies the maximum number of pages a class can get;
  35     'limit' in essence can be considered as the 'hard limit'
  36
  37 Rest of this document details how these two parameters are used in the
  38 memory allocation logic.
  39
  40 Note that the numbers that are specified in the shares file, doesn't
  41 directly correspond to the number of pages. But, the user can make
  42 it so by making the total_guarantee and max_limit of the default class
  43 (/rcfs/taskclass) to be the total number of pages(given in config file)
  44 available in the system.
  45
  46   for example:
  47    # cd /rcfs/taskclass
  48    # cat config
  49    res=mem;tot_pages=239778,active=60473,inactive=135285,free=44555
  50    # cat shares
  51    res=mem,guarantee=-2,limit=-2,total_guarantee=100,max_limit=100
  52
  53   "tot_pages=239778" above mean there are 239778 lru pages in
  54   the system.
  55
  56   By making total_guarantee and max_limit to be same as this number at
  57   this level (/rcfs/taskclass), one can make guarantee and limit in all
  58   classes refer to the number of pages.
  59
  60   # echo 'res=mem,total_guarantee=239778,max_limit=239778' > shares
  61   # cat shares
  62   res=mem,guarantee=-2,limit=-2,total_guarantee=239778,max_limit=239778
  63
  64
  65 The number of pages a class can use be anywhere between its guarantee and
  66 limit. CKRM memory controller springs into action when the system needs
  67 to choose a victim page to swap out. While the number of pages a class can
  68 have allocated may be anywhere between its guarantee and limit, victim
  69 pages will be choosen from classes that are above their guarantee.
  70
  71 Pages will be freed from classes that are close to their "limit" before
  72 freeing pages from the classes that are close to their guarantee. Pages
  73 belonging to classes that are below their guarantee will not be chosen as
  74 a victim.
  75
  76 2. Core Design
  77 --------------------------
  78
  79 CKRM memory resource controller taps at appropriate low level memory
  80 management functions to associate a page with a class and to charge
  81 a class that brings the page to the LRU list.
  82
  83 2.1 Changes in page allocation function(__alloc_pages())
  84 --------------------------------------------------------
  85 - If the class that the current task belong to is over 110% of its 'limit',
  86   allocation of page(s) fail.
  87 - After succesful allocation of a page, the page is attached with the class
  88   to which the current task belongs to.
  89 - Note that the class is _not_ charged for the page(s) here.
  90
  91 2.2 Changes in page free(free_pages_bulk())
  92 -------------------------------------------
  93 - page is freed from the class it belongs to.
  94
  95 2.3 Adding/Deleting page to active/inactive list
  96 -------------------------------------------------
  97 When a page is added to the active or inactive list, the class that the
  98 page belongs to is charged for the page usage.
  99
 100 When a page is deleted from the active or inactive list, the class that the
 101 page belongs to is credited back.
 102
 103 If a class uses upto its limit, attempt is made to shrink the class's usage
 104 to 90% of its limit, in order to help the class stay within its limit.
 105 But, if the class is aggressive, and keep getting over the class's limit
 106 often(more than 10 shrink events in 10 seconds), then the memory resource
 107 controller gives up on the class and doesn't try to shrink the class, which
 108 will eventually lead the class to reach its 110% of its limit and then the
 109 page allocations will start failing.
 110
 111 2.4 Chages in the page reclaimation path (refill_inactive_zone and shrink_zone)
 112 -------------------------------------------------------------------------------
 113 Pages will be moved from active to inactive list(refill_inactive_zone) and
 114 pages from inactive list will be freed in the following order:
 115 (range is calculated by subtracting 'guarantee' from 'limit')
 116   - Classes that are over 110% of their range
 117   - Classes that are over 100% of their range
 118   - Classes that are over 75%  of their range
 119   - Classes that are over 50%  of their range
 120   - Classes that are over 25%  of their range
 121   - Classes whose parent is over 110% of its range
 122   - Classes that are over their guarantee
 123
 124 2.5 Handling of Shared pages
 125 ----------------------------
 126 Even if a mm is shared by tasks, the pages that belong to the mm will be
 127 charged against the individual tasks that bring the page into LRU.
 128
 129 But, when any task that is using a mm moves to a different class or exits,
 130 then all pages that belong to the mm will be charged against the richest
 131 class among the tasks that are using the mm.
 132
 133 Note: Shared page handling need to be improved with a better policy.
 134