blob: 0b3a1148f9f0414558ed0537b4219225162ccc3a [file] [log] [blame]
Seth Jennings61b0d762013-07-10 16:05:05 -07001Overview:
2
3Zswap is a lightweight compressed cache for swap pages. It takes pages that are
4in the process of being swapped out and attempts to compress them into a
5dynamically allocated RAM-based memory pool. zswap basically trades CPU cycles
6for potentially reduced swap I/O.  This trade-off can also result in a
7significant performance improvement if reads from the compressed cache are
8faster than reads from a swap device.
9
10NOTE: Zswap is a new feature as of v3.11 and interacts heavily with memory
Christian Hesse0151e3d2013-11-12 15:07:34 -080011reclaim. This interaction has not been fully explored on the large set of
Seth Jennings61b0d762013-07-10 16:05:05 -070012potential configurations and workloads that exist. For this reason, zswap
13is a work in progress and should be considered experimental.
14
15Some potential benefits:
16* Desktop/laptop users with limited RAM capacities can mitigate the
17    performance impact of swapping.
18* Overcommitted guests that share a common I/O resource can
19    dramatically reduce their swap I/O pressure, avoiding heavy handed I/O
20 throttling by the hypervisor. This allows more work to get done with less
21 impact to the guest workload and guests sharing the I/O subsystem
22* Users with SSDs as swap devices can extend the life of the device by
23    drastically reducing life-shortening writes.
24
25Zswap evicts pages from compressed cache on an LRU basis to the backing swap
Christian Hesse0151e3d2013-11-12 15:07:34 -080026device when the compressed pool reaches its size limit. This requirement had
Seth Jennings61b0d762013-07-10 16:05:05 -070027been identified in prior community discussions.
28
Dan Streetmanc00ed162015-06-25 15:00:35 -070029Zswap is disabled by default but can be enabled at boot time by setting
30the "enabled" attribute to 1 at boot time. ie: zswap.enabled=1. Zswap
31can also be enabled and disabled at runtime using the sysfs interface.
32An example command to enable zswap at runtime, assuming sysfs is mounted
33at /sys, is:
34
Dan Streetman9c4c5ef2015-09-09 15:35:25 -070035echo 1 > /sys/module/zswap/parameters/enabled
Dan Streetmanc00ed162015-06-25 15:00:35 -070036
37When zswap is disabled at runtime it will stop storing pages that are
38being swapped out. However, it will _not_ immediately write out or fault
39back into memory all of the pages stored in the compressed pool. The
40pages stored in zswap will remain in the compressed pool until they are
41either invalidated or faulted back into memory. In order to force all
42pages out of the compressed pool, a swapoff on the swap device(s) will
43fault back into memory all swapped out pages, including those in the
44compressed pool.
Seth Jennings61b0d762013-07-10 16:05:05 -070045
46Design:
47
48Zswap receives pages for compression through the Frontswap API and is able to
49evict pages from its own compressed pool on an LRU basis and write them back to
50the backing swap device in the case that the compressed pool is full.
51
Dan Streetman9c4c5ef2015-09-09 15:35:25 -070052Zswap makes use of zpool for the managing the compressed memory pool. Each
53allocation in zpool is not directly accessible by address. Rather, a handle is
Christian Hesse0151e3d2013-11-12 15:07:34 -080054returned by the allocation routine and that handle must be mapped before being
Seth Jennings61b0d762013-07-10 16:05:05 -070055accessed. The compressed memory pool grows on demand and shrinks as compressed
Dan Streetman9c4c5ef2015-09-09 15:35:25 -070056pages are freed. The pool is not preallocated. By default, a zpool of type
57zbud is created, but it can be selected at boot time by setting the "zpool"
58attribute, e.g. zswap.zpool=zbud. It can also be changed at runtime using the
59sysfs "zpool" attribute, e.g.
60
61echo zbud > /sys/module/zswap/parameters/zpool
62
63The zbud type zpool allocates exactly 1 page to store 2 compressed pages, which
64means the compression ratio will always be 2:1 or worse (because of half-full
65zbud pages). The zsmalloc type zpool has a more complex compressed page
66storage method, and it can achieve greater storage densities. However,
67zsmalloc does not implement compressed page eviction, so once zswap fills it
68cannot evict the oldest page, it can only reject new pages.
Seth Jennings61b0d762013-07-10 16:05:05 -070069
70When a swap page is passed from frontswap to zswap, zswap maintains a mapping
Dan Streetman9c4c5ef2015-09-09 15:35:25 -070071of the swap entry, a combination of the swap type and swap offset, to the zpool
Seth Jennings61b0d762013-07-10 16:05:05 -070072handle that references that compressed swap page. This mapping is achieved
73with a red-black tree per swap type. The swap offset is the search key for the
74tree nodes.
75
76During a page fault on a PTE that is a swap entry, frontswap calls the zswap
77load function to decompress the page into the page allocated by the page fault
78handler.
79
80Once there are no PTEs referencing a swap page stored in zswap (i.e. the count
81in the swap_map goes to 0) the swap code calls the zswap invalidate function,
82via frontswap, to free the compressed entry.
83
84Zswap seeks to be simple in its policies. Sysfs attributes allow for one user
Christian Hesse0151e3d2013-11-12 15:07:34 -080085controlled policy:
Seth Jennings61b0d762013-07-10 16:05:05 -070086* max_pool_percent - The maximum percentage of memory that the compressed
87 pool can occupy.
88
Dan Streetman9c4c5ef2015-09-09 15:35:25 -070089The default compressor is lzo, but it can be selected at boot time by setting
90the “compressor” attribute, e.g. zswap.compressor=lzo. It can also be changed
91at runtime using the sysfs "compressor" attribute, e.g.
92
93echo lzo > /sys/module/zswap/parameters/compressor
94
95When the zpool and/or compressor parameter is changed at runtime, any existing
96compressed pages are not modified; they are left in their own zpool. When a
97request is made for a page in an old zpool, it is uncompressed using its
98original compressor. Once all pages are removed from an old zpool, the zpool
99and its compressor are freed.
Seth Jennings61b0d762013-07-10 16:05:05 -0700100
Srividya Desireddy51f73ff2017-12-14 15:32:45 -0800101Some of the pages in zswap are same-value filled pages (i.e. contents of the
102page have same value or repetitive pattern). These pages include zero-filled
103pages and they are handled differently. During store operation, a page is
104checked if it is a same-value filled page before compressing it. If true, the
105compressed length of the page is set to zero and the pattern or same-filled
106value is stored.
107
108Same-value filled pages identification feature is enabled by default and can be
109disabled at boot time by setting the "same_filled_pages_enabled" attribute to 0,
110e.g. zswap.same_filled_pages_enabled=0. It can also be enabled and disabled at
111runtime using the sysfs "same_filled_pages_enabled" attribute, e.g.
112
113echo 1 > /sys/module/zswap/parameters/same_filled_pages_enabled
114
115When zswap same-filled page identification is disabled at runtime, it will stop
116checking for the same-value filled pages during store operation. However, the
117existing pages which are marked as same-value filled pages remain stored
118unchanged in zswap until they are either loaded or invalidated.
119
Seth Jennings61b0d762013-07-10 16:05:05 -0700120A debugfs interface is provided for various statistic about pool size, number
Srividya Desireddy51f73ff2017-12-14 15:32:45 -0800121of pages stored, same-value filled pages and various counters for the reasons
122pages are rejected.