Documentation/admin-guide/mm/zswap.rst

   1 =====
   2 zswap
   3 =====
   4
   5 Overview
   6 ========
   7
   8 Zswap is a lightweight compressed cache for swap pages. It takes pages that are
   9 in the process of being swapped out and attempts to compress them into a
  10 dynamically allocated RAM-based memory pool.  zswap basically trades CPU cycles
  11 for potentially reduced swap I/O.  This trade-off can also result in a
  12 significant performance improvement if reads from the compressed cache are
  13 faster than reads from a swap device.
  14
  15 Some potential benefits:
  16
  17 * Desktop/laptop users with limited RAM capacities can mitigate the
  18   performance impact of swapping.
  19 * Overcommitted guests that share a common I/O resource can
  20   dramatically reduce their swap I/O pressure, avoiding heavy handed I/O
  21   throttling by the hypervisor. This allows more work to get done with less
  22   impact to the guest workload and guests sharing the I/O subsystem
  23 * Users with SSDs as swap devices can extend the life of the device by
  24   drastically reducing life-shortening writes.
  25
  26 Zswap evicts pages from compressed cache on an LRU basis to the backing swap
  27 device when the compressed pool reaches its size limit.  This requirement had
  28 been identified in prior community discussions.
  29
  30 Whether Zswap is enabled at the boot time depends on whether
  31 the ``CONFIG_ZSWAP_DEFAULT_ON`` Kconfig option is enabled or not.
  32 This setting can then be overridden by providing the kernel command line
  33 ``zswap.enabled=`` option, for example ``zswap.enabled=0``.
  34 Zswap can also be enabled and disabled at runtime using the sysfs interface.
  35 An example command to enable zswap at runtime, assuming sysfs is mounted
  36 at ``/sys``, is::
  37
  38         echo 1 > /sys/module/zswap/parameters/enabled
  39
  40 When zswap is disabled at runtime it will stop storing pages that are
  41 being swapped out.  However, it will _not_ immediately write out or fault
  42 back into memory all of the pages stored in the compressed pool.  The
  43 pages stored in zswap will remain in the compressed pool until they are
  44 either invalidated or faulted back into memory.  In order to force all
  45 pages out of the compressed pool, a swapoff on the swap device(s) will
  46 fault back into memory all swapped out pages, including those in the
  47 compressed pool.
  48
  49 Design
  50 ======
  51
  52 Zswap receives pages for compression from the swap subsystem and is able to
  53 evict pages from its own compressed pool on an LRU basis and write them back to
  54 the backing swap device in the case that the compressed pool is full.
  55
  56 Zswap makes use of zpool for the managing the compressed memory pool.  Each
  57 allocation in zpool is not directly accessible by address.  Rather, a handle is
  58 returned by the allocation routine and that handle must be mapped before being
  59 accessed.  The compressed memory pool grows on demand and shrinks as compressed
  60 pages are freed.  The pool is not preallocated.  By default, a zpool
  61 of type selected in ``CONFIG_ZSWAP_ZPOOL_DEFAULT`` Kconfig option is created,
  62 but it can be overridden at boot time by setting the ``zpool`` attribute,
  63 e.g. ``zswap.zpool=zbud``. It can also be changed at runtime using the sysfs
  64 ``zpool`` attribute, e.g.::
  65
  66         echo zbud > /sys/module/zswap/parameters/zpool
  67
  68 The zbud type zpool allocates exactly 1 page to store 2 compressed pages, which
  69 means the compression ratio will always be 2:1 or worse (because of half-full
  70 zbud pages).  The zsmalloc type zpool has a more complex compressed page
  71 storage method, and it can achieve greater storage densities.
  72
  73 When a swap page is passed from swapout to zswap, zswap maintains a mapping
  74 of the swap entry, a combination of the swap type and swap offset, to the zpool
  75 handle that references that compressed swap page.  This mapping is achieved
  76 with a red-black tree per swap type.  The swap offset is the search key for the
  77 tree nodes.
  78
  79 During a page fault on a PTE that is a swap entry, the swapin code calls the
  80 zswap load function to decompress the page into the page allocated by the page
  81 fault handler.
  82
  83 Once there are no PTEs referencing a swap page stored in zswap (i.e. the count
  84 in the swap_map goes to 0) the swap code calls the zswap invalidate function
  85 to free the compressed entry.
  86
  87 Zswap seeks to be simple in its policies.  Sysfs attributes allow for one user
  88 controlled policy:
  89
  90 * max_pool_percent - The maximum percentage of memory that the compressed
  91   pool can occupy.
  92
  93 The default compressor is selected in ``CONFIG_ZSWAP_COMPRESSOR_DEFAULT``
  94 Kconfig option, but it can be overridden at boot time by setting the
  95 ``compressor`` attribute, e.g. ``zswap.compressor=lzo``.
  96 It can also be changed at runtime using the sysfs "compressor"
  97 attribute, e.g.::
  98
  99         echo lzo > /sys/module/zswap/parameters/compressor
 100
 101 When the zpool and/or compressor parameter is changed at runtime, any existing
 102 compressed pages are not modified; they are left in their own zpool.  When a
 103 request is made for a page in an old zpool, it is uncompressed using its
 104 original compressor.  Once all pages are removed from an old zpool, the zpool
 105 and its compressor are freed.
 106
 107 Some of the pages in zswap are same-value filled pages (i.e. contents of the
 108 page have same value or repetitive pattern). These pages include zero-filled
 109 pages and they are handled differently. During store operation, a page is
 110 checked if it is a same-value filled page before compressing it. If true, the
 111 compressed length of the page is set to zero and the pattern or same-filled
 112 value is stored.
 113
 114 Same-value filled pages identification feature is enabled by default and can be
 115 disabled at boot time by setting the ``same_filled_pages_enabled`` attribute
 116 to 0, e.g. ``zswap.same_filled_pages_enabled=0``. It can also be enabled and
 117 disabled at runtime using the sysfs ``same_filled_pages_enabled``
 118 attribute, e.g.::
 119
 120         echo 1 > /sys/module/zswap/parameters/same_filled_pages_enabled
 121
 122 When zswap same-filled page identification is disabled at runtime, it will stop
 123 checking for the same-value filled pages during store operation.
 124 In other words, every page will be then considered non-same-value filled.
 125 However, the existing pages which are marked as same-value filled pages remain
 126 stored unchanged in zswap until they are either loaded or invalidated.
 127
 128 In some circumstances it might be advantageous to make use of just the zswap
 129 ability to efficiently store same-filled pages without enabling the whole
 130 compressed page storage.
 131 In this case the handling of non-same-value pages by zswap (enabled by default)
 132 can be disabled by setting the ``non_same_filled_pages_enabled`` attribute
 133 to 0, e.g. ``zswap.non_same_filled_pages_enabled=0``.
 134 It can also be enabled and disabled at runtime using the sysfs
 135 ``non_same_filled_pages_enabled`` attribute, e.g.::
 136
 137         echo 1 > /sys/module/zswap/parameters/non_same_filled_pages_enabled
 138
 139 Disabling both ``zswap.same_filled_pages_enabled`` and
 140 ``zswap.non_same_filled_pages_enabled`` effectively disables accepting any new
 141 pages by zswap.
 142
 143 To prevent zswap from shrinking pool when zswap is full and there's a high
 144 pressure on swap (this will result in flipping pages in and out zswap pool
 145 without any real benefit but with a performance drop for the system), a
 146 special parameter has been introduced to implement a sort of hysteresis to
 147 refuse taking pages into zswap pool until it has sufficient space if the limit
 148 has been hit. To set the threshold at which zswap would start accepting pages
 149 again after it became full, use the sysfs ``accept_threshold_percent``
 150 attribute, e. g.::
 151
 152         echo 80 > /sys/module/zswap/parameters/accept_threshold_percent
 153
 154 Setting this parameter to 100 will disable the hysteresis.
 155
 156 A debugfs interface is provided for various statistic about pool size, number
 157 of pages stored, same-value filled pages and various counters for the reasons
 158 pages are rejected.