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