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