Commit | Line | Data |
---|---|---|
3406bb5c MR |
1 | .. _zswap: |
2 | ||
3 | ===== | |
4 | zswap | |
5 | ===== | |
6 | ||
7 | Overview | |
8 | ======== | |
61b0d760 SJ |
9 | |
10 | Zswap is a lightweight compressed cache for swap pages. It takes pages that are | |
11 | in the process of being swapped out and attempts to compress them into a | |
12 | dynamically allocated RAM-based memory pool. zswap basically trades CPU cycles | |
13 | for potentially reduced swap I/O. This trade-off can also result in a | |
14 | significant performance improvement if reads from the compressed cache are | |
15 | faster than reads from a swap device. | |
16 | ||
3406bb5c MR |
17 | .. note:: |
18 | Zswap is a new feature as of v3.11 and interacts heavily with memory | |
19 | reclaim. This interaction has not been fully explored on the large set of | |
20 | potential configurations and workloads that exist. For this reason, zswap | |
21 | is a work in progress and should be considered experimental. | |
22 | ||
23 | Some potential benefits: | |
61b0d760 | 24 | |
61b0d760 | 25 | * Desktop/laptop users with limited RAM capacities can mitigate the |
3406bb5c | 26 | performance impact of swapping. |
61b0d760 | 27 | * Overcommitted guests that share a common I/O resource can |
3406bb5c MR |
28 | dramatically reduce their swap I/O pressure, avoiding heavy handed I/O |
29 | throttling by the hypervisor. This allows more work to get done with less | |
30 | impact to the guest workload and guests sharing the I/O subsystem | |
61b0d760 | 31 | * Users with SSDs as swap devices can extend the life of the device by |
3406bb5c | 32 | drastically reducing life-shortening writes. |
61b0d760 SJ |
33 | |
34 | Zswap evicts pages from compressed cache on an LRU basis to the backing swap | |
0151e3d6 | 35 | device when the compressed pool reaches its size limit. This requirement had |
61b0d760 SJ |
36 | been identified in prior community discussions. |
37 | ||
bb8b93b5 MS |
38 | Whether Zswap is enabled at the boot time depends on whether |
39 | the ``CONFIG_ZSWAP_DEFAULT_ON`` Kconfig option is enabled or not. | |
40 | This setting can then be overridden by providing the kernel command line | |
41 | ``zswap.enabled=`` option, for example ``zswap.enabled=0``. | |
42 | Zswap can also be enabled and disabled at runtime using the sysfs interface. | |
c00ed16a | 43 | An example command to enable zswap at runtime, assuming sysfs is mounted |
3406bb5c | 44 | at ``/sys``, is:: |
c00ed16a | 45 | |
3406bb5c | 46 | echo 1 > /sys/module/zswap/parameters/enabled |
c00ed16a DS |
47 | |
48 | When zswap is disabled at runtime it will stop storing pages that are | |
49 | being swapped out. However, it will _not_ immediately write out or fault | |
50 | back into memory all of the pages stored in the compressed pool. The | |
51 | pages stored in zswap will remain in the compressed pool until they are | |
52 | either invalidated or faulted back into memory. In order to force all | |
53 | pages out of the compressed pool, a swapoff on the swap device(s) will | |
54 | fault back into memory all swapped out pages, including those in the | |
55 | compressed pool. | |
61b0d760 | 56 | |
3406bb5c MR |
57 | Design |
58 | ====== | |
61b0d760 SJ |
59 | |
60 | Zswap receives pages for compression through the Frontswap API and is able to | |
61 | evict pages from its own compressed pool on an LRU basis and write them back to | |
62 | the backing swap device in the case that the compressed pool is full. | |
63 | ||
9c4c5ef3 DS |
64 | Zswap makes use of zpool for the managing the compressed memory pool. Each |
65 | allocation in zpool is not directly accessible by address. Rather, a handle is | |
0151e3d6 | 66 | returned by the allocation routine and that handle must be mapped before being |
61b0d760 | 67 | accessed. The compressed memory pool grows on demand and shrinks as compressed |
3406bb5c | 68 | pages are freed. The pool is not preallocated. By default, a zpool |
bb8b93b5 MS |
69 | of type selected in ``CONFIG_ZSWAP_ZPOOL_DEFAULT`` Kconfig option is created, |
70 | but it can be overridden at boot time by setting the ``zpool`` attribute, | |
71 | e.g. ``zswap.zpool=zbud``. It can also be changed at runtime using the sysfs | |
72 | ``zpool`` attribute, e.g.:: | |
9c4c5ef3 | 73 | |
3406bb5c | 74 | echo zbud > /sys/module/zswap/parameters/zpool |
9c4c5ef3 DS |
75 | |
76 | The zbud type zpool allocates exactly 1 page to store 2 compressed pages, which | |
77 | means the compression ratio will always be 2:1 or worse (because of half-full | |
78 | zbud pages). The zsmalloc type zpool has a more complex compressed page | |
79 | storage method, and it can achieve greater storage densities. However, | |
80 | zsmalloc does not implement compressed page eviction, so once zswap fills it | |
81 | cannot evict the oldest page, it can only reject new pages. | |
61b0d760 SJ |
82 | |
83 | When a swap page is passed from frontswap to zswap, zswap maintains a mapping | |
9c4c5ef3 | 84 | of the swap entry, a combination of the swap type and swap offset, to the zpool |
61b0d760 SJ |
85 | handle that references that compressed swap page. This mapping is achieved |
86 | with a red-black tree per swap type. The swap offset is the search key for the | |
87 | tree nodes. | |
88 | ||
89 | During a page fault on a PTE that is a swap entry, frontswap calls the zswap | |
90 | load function to decompress the page into the page allocated by the page fault | |
91 | handler. | |
92 | ||
93 | Once there are no PTEs referencing a swap page stored in zswap (i.e. the count | |
94 | in the swap_map goes to 0) the swap code calls the zswap invalidate function, | |
95 | via frontswap, to free the compressed entry. | |
96 | ||
97 | Zswap seeks to be simple in its policies. Sysfs attributes allow for one user | |
0151e3d6 | 98 | controlled policy: |
3406bb5c | 99 | |
61b0d760 | 100 | * max_pool_percent - The maximum percentage of memory that the compressed |
3406bb5c | 101 | pool can occupy. |
61b0d760 | 102 | |
bb8b93b5 MS |
103 | The default compressor is selected in ``CONFIG_ZSWAP_COMPRESSOR_DEFAULT`` |
104 | Kconfig option, but it can be overridden at boot time by setting the | |
105 | ``compressor`` attribute, e.g. ``zswap.compressor=lzo``. | |
3406bb5c MR |
106 | It can also be changed at runtime using the sysfs "compressor" |
107 | attribute, e.g.:: | |
9c4c5ef3 | 108 | |
3406bb5c | 109 | echo lzo > /sys/module/zswap/parameters/compressor |
9c4c5ef3 DS |
110 | |
111 | When the zpool and/or compressor parameter is changed at runtime, any existing | |
112 | compressed pages are not modified; they are left in their own zpool. When a | |
113 | request is made for a page in an old zpool, it is uncompressed using its | |
114 | original compressor. Once all pages are removed from an old zpool, the zpool | |
115 | and its compressor are freed. | |
61b0d760 | 116 | |
51f73fff SD |
117 | Some of the pages in zswap are same-value filled pages (i.e. contents of the |
118 | page have same value or repetitive pattern). These pages include zero-filled | |
119 | pages and they are handled differently. During store operation, a page is | |
120 | checked if it is a same-value filled page before compressing it. If true, the | |
121 | compressed length of the page is set to zero and the pattern or same-filled | |
122 | value is stored. | |
123 | ||
124 | Same-value filled pages identification feature is enabled by default and can be | |
3406bb5c MR |
125 | disabled at boot time by setting the ``same_filled_pages_enabled`` attribute |
126 | to 0, e.g. ``zswap.same_filled_pages_enabled=0``. It can also be enabled and | |
127 | disabled at runtime using the sysfs ``same_filled_pages_enabled`` | |
128 | attribute, e.g.:: | |
51f73fff | 129 | |
3406bb5c | 130 | echo 1 > /sys/module/zswap/parameters/same_filled_pages_enabled |
51f73fff SD |
131 | |
132 | When zswap same-filled page identification is disabled at runtime, it will stop | |
133 | checking for the same-value filled pages during store operation. However, the | |
134 | existing pages which are marked as same-value filled pages remain stored | |
135 | unchanged in zswap until they are either loaded or invalidated. | |
136 | ||
45190f01 VW |
137 | To prevent zswap from shrinking pool when zswap is full and there's a high |
138 | pressure on swap (this will result in flipping pages in and out zswap pool | |
139 | without any real benefit but with a performance drop for the system), a | |
140 | special parameter has been introduced to implement a sort of hysteresis to | |
141 | refuse taking pages into zswap pool until it has sufficient space if the limit | |
142 | has been hit. To set the threshold at which zswap would start accepting pages | |
9469b390 | 143 | again after it became full, use the sysfs ``accept_threshold_percent`` |
45190f01 VW |
144 | attribute, e. g.:: |
145 | ||
9469b390 | 146 | echo 80 > /sys/module/zswap/parameters/accept_threshold_percent |
45190f01 VW |
147 | |
148 | Setting this parameter to 100 will disable the hysteresis. | |
149 | ||
61b0d760 | 150 | A debugfs interface is provided for various statistic about pool size, number |
51f73fff SD |
151 | of pages stored, same-value filled pages and various counters for the reasons |
152 | pages are rejected. |