1===== 2zswap 3===== 4 5Overview 6======== 7 8Zswap is a lightweight compressed cache for swap pages. It takes pages that are 9in the process of being swapped out and attempts to compress them into a 10dynamically allocated RAM-based memory pool. zswap basically trades CPU cycles 11for potentially reduced swap I/O. This trade-off can also result in a 12significant performance improvement if reads from the compressed cache are 13faster than reads from a swap device. 14 15Some 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 26Zswap evicts pages from compressed cache on an LRU basis to the backing swap 27device when the compressed pool reaches its size limit. This requirement had 28been identified in prior community discussions. 29 30Whether Zswap is enabled at the boot time depends on whether 31the ``CONFIG_ZSWAP_DEFAULT_ON`` Kconfig option is enabled or not. 32This setting can then be overridden by providing the kernel command line 33``zswap.enabled=`` option, for example ``zswap.enabled=0``. 34Zswap can also be enabled and disabled at runtime using the sysfs interface. 35An example command to enable zswap at runtime, assuming sysfs is mounted 36at ``/sys``, is:: 37 38 echo 1 > /sys/module/zswap/parameters/enabled 39 40When zswap is disabled at runtime it will stop storing pages that are 41being swapped out. However, it will _not_ immediately write out or fault 42back into memory all of the pages stored in the compressed pool. The 43pages stored in zswap will remain in the compressed pool until they are 44either invalidated or faulted back into memory. In order to force all 45pages out of the compressed pool, a swapoff on the swap device(s) will 46fault back into memory all swapped out pages, including those in the 47compressed pool. 48 49Design 50====== 51 52Zswap receives pages for compression from the swap subsystem and is able to 53evict pages from its own compressed pool on an LRU basis and write them back to 54the backing swap device in the case that the compressed pool is full. 55 56Zswap makes use of zsmalloc for the managing the compressed memory pool. Each 57allocation in zsmalloc is not directly accessible by address. Rather, a handle is 58returned by the allocation routine and that handle must be mapped before being 59accessed. The compressed memory pool grows on demand and shrinks as compressed 60pages are freed. The pool is not preallocated. 61 62When a swap page is passed from swapout to zswap, zswap maintains a mapping 63of the swap entry, a combination of the swap type and swap offset, to the 64zsmalloc handle that references that compressed swap page. This mapping is 65achieved with a red-black tree per swap type. The swap offset is the search 66key for the tree nodes. 67 68During a page fault on a PTE that is a swap entry, the swapin code calls the 69zswap load function to decompress the page into the page allocated by the page 70fault handler. 71 72Once there are no PTEs referencing a swap page stored in zswap (i.e. the count 73in the swap_map goes to 0) the swap code calls the zswap invalidate function 74to free the compressed entry. 75 76Zswap seeks to be simple in its policies. Sysfs attributes allow for one user 77controlled policy: 78 79* max_pool_percent - The maximum percentage of memory that the compressed 80 pool can occupy. 81 82The default compressor is selected in ``CONFIG_ZSWAP_COMPRESSOR_DEFAULT`` 83Kconfig option, but it can be overridden at boot time by setting the 84``compressor`` attribute, e.g. ``zswap.compressor=lzo``. 85It can also be changed at runtime using the sysfs "compressor" 86attribute, e.g.:: 87 88 echo lzo > /sys/module/zswap/parameters/compressor 89 90When the compressor parameter is changed at runtime, any existing compressed 91pages are not modified; they are left in their own pool. When a request is 92made for a page in an old pool, it is uncompressed using its original 93compressor. Once all pages are removed from an old pool, the pool and its 94compressor are freed. 95 96Some of the pages in zswap are same-value filled pages (i.e. contents of the 97page have same value or repetitive pattern). These pages include zero-filled 98pages and they are handled differently. During store operation, a page is 99checked if it is a same-value filled page before compressing it. If true, the 100compressed length of the page is set to zero and the pattern or same-filled 101value is stored. 102 103To prevent zswap from shrinking pool when zswap is full and there's a high 104pressure on swap (this will result in flipping pages in and out zswap pool 105without any real benefit but with a performance drop for the system), a 106special parameter has been introduced to implement a sort of hysteresis to 107refuse taking pages into zswap pool until it has sufficient space if the limit 108has been hit. To set the threshold at which zswap would start accepting pages 109again after it became full, use the sysfs ``accept_threshold_percent`` 110attribute, e. g.:: 111 112 echo 80 > /sys/module/zswap/parameters/accept_threshold_percent 113 114Setting this parameter to 100 will disable the hysteresis. 115 116Some users cannot tolerate the swapping that comes with zswap store failures 117and zswap writebacks. Swapping can be disabled entirely (without disabling 118zswap itself) on a cgroup-basis as follows:: 119 120 echo 0 > /sys/fs/cgroup/<cgroup-name>/memory.zswap.writeback 121 122Note that if the store failures are recurring (for e.g if the pages are 123incompressible), users can observe reclaim inefficiency after disabling 124writeback (because the same pages might be rejected again and again). 125 126When there is a sizable amount of cold memory residing in the zswap pool, it 127can be advantageous to proactively write these cold pages to swap and reclaim 128the memory for other use cases. By default, the zswap shrinker is disabled. 129User can enable it as follows:: 130 131 echo Y > /sys/module/zswap/parameters/shrinker_enabled 132 133This can be enabled at the boot time if ``CONFIG_ZSWAP_SHRINKER_DEFAULT_ON`` is 134selected. 135 136A debugfs interface is provided for various statistic about pool size, number 137of pages stored, same-value filled pages and various counters for the reasons 138pages are rejected. 139