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 To prevent zswap from shrinking pool when zswap is full and there's a high 115 pressure on swap (this will result in flipping pages in and out zswap pool 116 without any real benefit but with a performance drop for the system), a 117 special parameter has been introduced to implement a sort of hysteresis to 118 refuse taking pages into zswap pool until it has sufficient space if the limit 119 has been hit. To set the threshold at which zswap would start accepting pages 120 again after it became full, use the sysfs ``accept_threshold_percent`` 121 attribute, e. g.:: 122 123 echo 80 > /sys/module/zswap/parameters/accept_threshold_percent 124 125 Setting this parameter to 100 will disable the hysteresis. 126 127 Some users cannot tolerate the swapping that comes with zswap store failures 128 and zswap writebacks. Swapping can be disabled entirely (without disabling 129 zswap itself) on a cgroup-basis as follows:: 130 131 echo 0 > /sys/fs/cgroup/<cgroup-name>/memory.zswap.writeback 132 133 Note that if the store failures are recurring (for e.g if the pages are 134 incompressible), users can observe reclaim inefficiency after disabling 135 writeback (because the same pages might be rejected again and again). 136 137 When there is a sizable amount of cold memory residing in the zswap pool, it 138 can be advantageous to proactively write these cold pages to swap and reclaim 139 the memory for other use cases. By default, the zswap shrinker is disabled. 140 User can enable it as follows:: 141 142 echo Y > /sys/module/zswap/parameters/shrinker_enabled 143 144 This can be enabled at the boot time if ``CONFIG_ZSWAP_SHRINKER_DEFAULT_ON`` is 145 selected. 146 147 A debugfs interface is provided for various statistic about pool size, number 148 of pages stored, same-value filled pages and various counters for the reasons 149 pages are rejected.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.