Documentation/vm/zswap.rst

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