1ad782c48SSeongJae Park.. _zswap: 2ad782c48SSeongJae Park 3ad782c48SSeongJae Park===== 4ad782c48SSeongJae Parkzswap 5ad782c48SSeongJae Park===== 6ad782c48SSeongJae Park 7ad782c48SSeongJae ParkOverview 8ad782c48SSeongJae Park======== 9ad782c48SSeongJae Park 10ad782c48SSeongJae ParkZswap is a lightweight compressed cache for swap pages. It takes pages that are 11ad782c48SSeongJae Parkin the process of being swapped out and attempts to compress them into a 12ad782c48SSeongJae Parkdynamically allocated RAM-based memory pool. zswap basically trades CPU cycles 13ad782c48SSeongJae Parkfor potentially reduced swap I/O. This trade-off can also result in a 14ad782c48SSeongJae Parksignificant performance improvement if reads from the compressed cache are 15ad782c48SSeongJae Parkfaster than reads from a swap device. 16ad782c48SSeongJae Park 17ad782c48SSeongJae ParkSome potential benefits: 18ad782c48SSeongJae Park 19ad782c48SSeongJae Park* Desktop/laptop users with limited RAM capacities can mitigate the 20ad782c48SSeongJae Park performance impact of swapping. 21ad782c48SSeongJae Park* Overcommitted guests that share a common I/O resource can 22ad782c48SSeongJae Park dramatically reduce their swap I/O pressure, avoiding heavy handed I/O 23ad782c48SSeongJae Park throttling by the hypervisor. This allows more work to get done with less 24ad782c48SSeongJae Park impact to the guest workload and guests sharing the I/O subsystem 25ad782c48SSeongJae Park* Users with SSDs as swap devices can extend the life of the device by 26ad782c48SSeongJae Park drastically reducing life-shortening writes. 27ad782c48SSeongJae Park 28ad782c48SSeongJae ParkZswap evicts pages from compressed cache on an LRU basis to the backing swap 29ad782c48SSeongJae Parkdevice when the compressed pool reaches its size limit. This requirement had 30ad782c48SSeongJae Parkbeen identified in prior community discussions. 31ad782c48SSeongJae Park 32ad782c48SSeongJae ParkWhether Zswap is enabled at the boot time depends on whether 33ad782c48SSeongJae Parkthe ``CONFIG_ZSWAP_DEFAULT_ON`` Kconfig option is enabled or not. 34ad782c48SSeongJae ParkThis setting can then be overridden by providing the kernel command line 35ad782c48SSeongJae Park``zswap.enabled=`` option, for example ``zswap.enabled=0``. 36ad782c48SSeongJae ParkZswap can also be enabled and disabled at runtime using the sysfs interface. 37ad782c48SSeongJae ParkAn example command to enable zswap at runtime, assuming sysfs is mounted 38ad782c48SSeongJae Parkat ``/sys``, is:: 39ad782c48SSeongJae Park 40ad782c48SSeongJae Park echo 1 > /sys/module/zswap/parameters/enabled 41ad782c48SSeongJae Park 42ad782c48SSeongJae ParkWhen zswap is disabled at runtime it will stop storing pages that are 43ad782c48SSeongJae Parkbeing swapped out. However, it will _not_ immediately write out or fault 44ad782c48SSeongJae Parkback into memory all of the pages stored in the compressed pool. The 45ad782c48SSeongJae Parkpages stored in zswap will remain in the compressed pool until they are 46ad782c48SSeongJae Parkeither invalidated or faulted back into memory. In order to force all 47ad782c48SSeongJae Parkpages out of the compressed pool, a swapoff on the swap device(s) will 48ad782c48SSeongJae Parkfault back into memory all swapped out pages, including those in the 49ad782c48SSeongJae Parkcompressed pool. 50ad782c48SSeongJae Park 51ad782c48SSeongJae ParkDesign 52ad782c48SSeongJae Park====== 53ad782c48SSeongJae Park 54ad782c48SSeongJae ParkZswap receives pages for compression through the Frontswap API and is able to 55ad782c48SSeongJae Parkevict pages from its own compressed pool on an LRU basis and write them back to 56ad782c48SSeongJae Parkthe backing swap device in the case that the compressed pool is full. 57ad782c48SSeongJae Park 58ad782c48SSeongJae ParkZswap makes use of zpool for the managing the compressed memory pool. Each 59ad782c48SSeongJae Parkallocation in zpool is not directly accessible by address. Rather, a handle is 60ad782c48SSeongJae Parkreturned by the allocation routine and that handle must be mapped before being 61ad782c48SSeongJae Parkaccessed. The compressed memory pool grows on demand and shrinks as compressed 62ad782c48SSeongJae Parkpages are freed. The pool is not preallocated. By default, a zpool 63ad782c48SSeongJae Parkof type selected in ``CONFIG_ZSWAP_ZPOOL_DEFAULT`` Kconfig option is created, 64ad782c48SSeongJae Parkbut it can be overridden at boot time by setting the ``zpool`` attribute, 65ad782c48SSeongJae Parke.g. ``zswap.zpool=zbud``. It can also be changed at runtime using the sysfs 66ad782c48SSeongJae Park``zpool`` attribute, e.g.:: 67ad782c48SSeongJae Park 68ad782c48SSeongJae Park echo zbud > /sys/module/zswap/parameters/zpool 69ad782c48SSeongJae Park 70ad782c48SSeongJae ParkThe zbud type zpool allocates exactly 1 page to store 2 compressed pages, which 71ad782c48SSeongJae Parkmeans the compression ratio will always be 2:1 or worse (because of half-full 72ad782c48SSeongJae Parkzbud pages). The zsmalloc type zpool has a more complex compressed page 73*1beb8ae3SNhat Phamstorage method, and it can achieve greater storage densities. 74ad782c48SSeongJae Park 75ad782c48SSeongJae ParkWhen a swap page is passed from frontswap to zswap, zswap maintains a mapping 76ad782c48SSeongJae Parkof the swap entry, a combination of the swap type and swap offset, to the zpool 77ad782c48SSeongJae Parkhandle that references that compressed swap page. This mapping is achieved 78ad782c48SSeongJae Parkwith a red-black tree per swap type. The swap offset is the search key for the 79ad782c48SSeongJae Parktree nodes. 80ad782c48SSeongJae Park 81ad782c48SSeongJae ParkDuring a page fault on a PTE that is a swap entry, frontswap calls the zswap 82ad782c48SSeongJae Parkload function to decompress the page into the page allocated by the page fault 83ad782c48SSeongJae Parkhandler. 84ad782c48SSeongJae Park 85ad782c48SSeongJae ParkOnce there are no PTEs referencing a swap page stored in zswap (i.e. the count 86ad782c48SSeongJae Parkin the swap_map goes to 0) the swap code calls the zswap invalidate function, 87ad782c48SSeongJae Parkvia frontswap, to free the compressed entry. 88ad782c48SSeongJae Park 89ad782c48SSeongJae ParkZswap seeks to be simple in its policies. Sysfs attributes allow for one user 90ad782c48SSeongJae Parkcontrolled policy: 91ad782c48SSeongJae Park 92ad782c48SSeongJae Park* max_pool_percent - The maximum percentage of memory that the compressed 93ad782c48SSeongJae Park pool can occupy. 94ad782c48SSeongJae Park 95ad782c48SSeongJae ParkThe default compressor is selected in ``CONFIG_ZSWAP_COMPRESSOR_DEFAULT`` 96ad782c48SSeongJae ParkKconfig option, but it can be overridden at boot time by setting the 97ad782c48SSeongJae Park``compressor`` attribute, e.g. ``zswap.compressor=lzo``. 98ad782c48SSeongJae ParkIt can also be changed at runtime using the sysfs "compressor" 99ad782c48SSeongJae Parkattribute, e.g.:: 100ad782c48SSeongJae Park 101ad782c48SSeongJae Park echo lzo > /sys/module/zswap/parameters/compressor 102ad782c48SSeongJae Park 103ad782c48SSeongJae ParkWhen the zpool and/or compressor parameter is changed at runtime, any existing 104ad782c48SSeongJae Parkcompressed pages are not modified; they are left in their own zpool. When a 105ad782c48SSeongJae Parkrequest is made for a page in an old zpool, it is uncompressed using its 106ad782c48SSeongJae Parkoriginal compressor. Once all pages are removed from an old zpool, the zpool 107ad782c48SSeongJae Parkand its compressor are freed. 108ad782c48SSeongJae Park 109ad782c48SSeongJae ParkSome of the pages in zswap are same-value filled pages (i.e. contents of the 110ad782c48SSeongJae Parkpage have same value or repetitive pattern). These pages include zero-filled 111ad782c48SSeongJae Parkpages and they are handled differently. During store operation, a page is 112ad782c48SSeongJae Parkchecked if it is a same-value filled page before compressing it. If true, the 113ad782c48SSeongJae Parkcompressed length of the page is set to zero and the pattern or same-filled 114ad782c48SSeongJae Parkvalue is stored. 115ad782c48SSeongJae Park 116ad782c48SSeongJae ParkSame-value filled pages identification feature is enabled by default and can be 117ad782c48SSeongJae Parkdisabled at boot time by setting the ``same_filled_pages_enabled`` attribute 118ad782c48SSeongJae Parkto 0, e.g. ``zswap.same_filled_pages_enabled=0``. It can also be enabled and 119ad782c48SSeongJae Parkdisabled at runtime using the sysfs ``same_filled_pages_enabled`` 120ad782c48SSeongJae Parkattribute, e.g.:: 121ad782c48SSeongJae Park 122ad782c48SSeongJae Park echo 1 > /sys/module/zswap/parameters/same_filled_pages_enabled 123ad782c48SSeongJae Park 124ad782c48SSeongJae ParkWhen zswap same-filled page identification is disabled at runtime, it will stop 125cb325dddSMaciej S. Szmigierochecking for the same-value filled pages during store operation. 126cb325dddSMaciej S. SzmigieroIn other words, every page will be then considered non-same-value filled. 127cb325dddSMaciej S. SzmigieroHowever, the existing pages which are marked as same-value filled pages remain 128cb325dddSMaciej S. Szmigierostored unchanged in zswap until they are either loaded or invalidated. 129cb325dddSMaciej S. Szmigiero 130cb325dddSMaciej S. SzmigieroIn some circumstances it might be advantageous to make use of just the zswap 131cb325dddSMaciej S. Szmigieroability to efficiently store same-filled pages without enabling the whole 132cb325dddSMaciej S. Szmigierocompressed page storage. 133cb325dddSMaciej S. SzmigieroIn this case the handling of non-same-value pages by zswap (enabled by default) 134cb325dddSMaciej S. Szmigierocan be disabled by setting the ``non_same_filled_pages_enabled`` attribute 135cb325dddSMaciej S. Szmigieroto 0, e.g. ``zswap.non_same_filled_pages_enabled=0``. 136cb325dddSMaciej S. SzmigieroIt can also be enabled and disabled at runtime using the sysfs 137cb325dddSMaciej S. Szmigiero``non_same_filled_pages_enabled`` attribute, e.g.:: 138cb325dddSMaciej S. Szmigiero 139cb325dddSMaciej S. Szmigiero echo 1 > /sys/module/zswap/parameters/non_same_filled_pages_enabled 140cb325dddSMaciej S. Szmigiero 141cb325dddSMaciej S. SzmigieroDisabling both ``zswap.same_filled_pages_enabled`` and 142cb325dddSMaciej S. Szmigiero``zswap.non_same_filled_pages_enabled`` effectively disables accepting any new 143cb325dddSMaciej S. Szmigieropages by zswap. 144ad782c48SSeongJae Park 145ad782c48SSeongJae ParkTo prevent zswap from shrinking pool when zswap is full and there's a high 146ad782c48SSeongJae Parkpressure on swap (this will result in flipping pages in and out zswap pool 147ad782c48SSeongJae Parkwithout any real benefit but with a performance drop for the system), a 148ad782c48SSeongJae Parkspecial parameter has been introduced to implement a sort of hysteresis to 149ad782c48SSeongJae Parkrefuse taking pages into zswap pool until it has sufficient space if the limit 150ad782c48SSeongJae Parkhas been hit. To set the threshold at which zswap would start accepting pages 151ad782c48SSeongJae Parkagain after it became full, use the sysfs ``accept_threshold_percent`` 152ad782c48SSeongJae Parkattribute, e. g.:: 153ad782c48SSeongJae Park 154ad782c48SSeongJae Park echo 80 > /sys/module/zswap/parameters/accept_threshold_percent 155ad782c48SSeongJae Park 156ad782c48SSeongJae ParkSetting this parameter to 100 will disable the hysteresis. 157ad782c48SSeongJae Park 158ad782c48SSeongJae ParkA debugfs interface is provided for various statistic about pool size, number 159ad782c48SSeongJae Parkof pages stored, same-value filled pages and various counters for the reasons 160ad782c48SSeongJae Parkpages are rejected. 161