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