1 ===== 1 =====
2 zswap 2 zswap
3 ===== 3 =====
4 4
5 Overview 5 Overview
6 ======== 6 ========
7 7
8 Zswap is a lightweight compressed cache for sw 8 Zswap is a lightweight compressed cache for swap pages. It takes pages that are
9 in the process of being swapped out and attemp 9 in the process of being swapped out and attempts to compress them into a
10 dynamically allocated RAM-based memory pool. 10 dynamically allocated RAM-based memory pool. zswap basically trades CPU cycles
11 for potentially reduced swap I/O. This trade- 11 for potentially reduced swap I/O. This trade-off can also result in a
12 significant performance improvement if reads f 12 significant performance improvement if reads from the compressed cache are
13 faster than reads from a swap device. 13 faster than reads from a swap device.
14 14
15 Some potential benefits: 15 Some potential benefits:
16 16
17 * Desktop/laptop users with limited RAM capaci 17 * Desktop/laptop users with limited RAM capacities can mitigate the
18 performance impact of swapping. 18 performance impact of swapping.
19 * Overcommitted guests that share a common I/O 19 * Overcommitted guests that share a common I/O resource can
20 dramatically reduce their swap I/O pressure, 20 dramatically reduce their swap I/O pressure, avoiding heavy handed I/O
21 throttling by the hypervisor. This allows mo 21 throttling by the hypervisor. This allows more work to get done with less
22 impact to the guest workload and guests shar 22 impact to the guest workload and guests sharing the I/O subsystem
23 * Users with SSDs as swap devices can extend t 23 * Users with SSDs as swap devices can extend the life of the device by
24 drastically reducing life-shortening writes. 24 drastically reducing life-shortening writes.
25 25
26 Zswap evicts pages from compressed cache on an 26 Zswap evicts pages from compressed cache on an LRU basis to the backing swap
27 device when the compressed pool reaches its si 27 device when the compressed pool reaches its size limit. This requirement had
28 been identified in prior community discussions 28 been identified in prior community discussions.
29 29
30 Whether Zswap is enabled at the boot time depe 30 Whether Zswap is enabled at the boot time depends on whether
31 the ``CONFIG_ZSWAP_DEFAULT_ON`` Kconfig option 31 the ``CONFIG_ZSWAP_DEFAULT_ON`` Kconfig option is enabled or not.
32 This setting can then be overridden by providi 32 This setting can then be overridden by providing the kernel command line
33 ``zswap.enabled=`` option, for example ``zswap 33 ``zswap.enabled=`` option, for example ``zswap.enabled=0``.
34 Zswap can also be enabled and disabled at runt 34 Zswap can also be enabled and disabled at runtime using the sysfs interface.
35 An example command to enable zswap at runtime, 35 An example command to enable zswap at runtime, assuming sysfs is mounted
36 at ``/sys``, is:: 36 at ``/sys``, is::
37 37
38 echo 1 > /sys/module/zswap/parameters/ 38 echo 1 > /sys/module/zswap/parameters/enabled
39 39
40 When zswap is disabled at runtime it will stop 40 When zswap is disabled at runtime it will stop storing pages that are
41 being swapped out. However, it will _not_ imm 41 being swapped out. However, it will _not_ immediately write out or fault
42 back into memory all of the pages stored in th 42 back into memory all of the pages stored in the compressed pool. The
43 pages stored in zswap will remain in the compr 43 pages stored in zswap will remain in the compressed pool until they are
44 either invalidated or faulted back into memory 44 either invalidated or faulted back into memory. In order to force all
45 pages out of the compressed pool, a swapoff on 45 pages out of the compressed pool, a swapoff on the swap device(s) will
46 fault back into memory all swapped out pages, 46 fault back into memory all swapped out pages, including those in the
47 compressed pool. 47 compressed pool.
48 48
49 Design 49 Design
50 ====== 50 ======
51 51
52 Zswap receives pages for compression from the 52 Zswap receives pages for compression from the swap subsystem and is able to
53 evict pages from its own compressed pool on an 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 c 54 the backing swap device in the case that the compressed pool is full.
55 55
56 Zswap makes use of zpool for the managing the 56 Zswap makes use of zpool for the managing the compressed memory pool. Each
57 allocation in zpool is not directly accessible 57 allocation in zpool is not directly accessible by address. Rather, a handle is
58 returned by the allocation routine and that ha 58 returned by the allocation routine and that handle must be mapped before being
59 accessed. The compressed memory pool grows on 59 accessed. The compressed memory pool grows on demand and shrinks as compressed
60 pages are freed. The pool is not preallocated 60 pages are freed. The pool is not preallocated. By default, a zpool
61 of type selected in ``CONFIG_ZSWAP_ZPOOL_DEFAU 61 of type selected in ``CONFIG_ZSWAP_ZPOOL_DEFAULT`` Kconfig option is created,
62 but it can be overridden at boot time by setti 62 but it can be overridden at boot time by setting the ``zpool`` attribute,
63 e.g. ``zswap.zpool=zbud``. It can also be chan 63 e.g. ``zswap.zpool=zbud``. It can also be changed at runtime using the sysfs
64 ``zpool`` attribute, e.g.:: 64 ``zpool`` attribute, e.g.::
65 65
66 echo zbud > /sys/module/zswap/paramete 66 echo zbud > /sys/module/zswap/parameters/zpool
67 67
68 The zbud type zpool allocates exactly 1 page t 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 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 mo 70 zbud pages). The zsmalloc type zpool has a more complex compressed page
71 storage method, and it can achieve greater sto 71 storage method, and it can achieve greater storage densities.
72 72
73 When a swap page is passed from swapout to zsw 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 t 74 of the swap entry, a combination of the swap type and swap offset, to the zpool
75 handle that references that compressed swap pa 75 handle that references that compressed swap page. This mapping is achieved
76 with a red-black tree per swap type. The swap 76 with a red-black tree per swap type. The swap offset is the search key for the
77 tree nodes. 77 tree nodes.
78 78
79 During a page fault on a PTE that is a swap en 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 int 80 zswap load function to decompress the page into the page allocated by the page
81 fault handler. 81 fault handler.
82 82
83 Once there are no PTEs referencing a swap page 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 84 in the swap_map goes to 0) the swap code calls the zswap invalidate function
85 to free the compressed entry. 85 to free the compressed entry.
86 86
87 Zswap seeks to be simple in its policies. Sys 87 Zswap seeks to be simple in its policies. Sysfs attributes allow for one user
88 controlled policy: 88 controlled policy:
89 89
90 * max_pool_percent - The maximum percentage of 90 * max_pool_percent - The maximum percentage of memory that the compressed
91 pool can occupy. 91 pool can occupy.
92 92
93 The default compressor is selected in ``CONFIG 93 The default compressor is selected in ``CONFIG_ZSWAP_COMPRESSOR_DEFAULT``
94 Kconfig option, but it can be overridden at bo 94 Kconfig option, but it can be overridden at boot time by setting the
95 ``compressor`` attribute, e.g. ``zswap.compres 95 ``compressor`` attribute, e.g. ``zswap.compressor=lzo``.
96 It can also be changed at runtime using the sy 96 It can also be changed at runtime using the sysfs "compressor"
97 attribute, e.g.:: 97 attribute, e.g.::
98 98
99 echo lzo > /sys/module/zswap/parameter 99 echo lzo > /sys/module/zswap/parameters/compressor
100 100
101 When the zpool and/or compressor parameter is 101 When the zpool and/or compressor parameter is changed at runtime, any existing
102 compressed pages are not modified; they are le 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 103 request is made for a page in an old zpool, it is uncompressed using its
104 original compressor. Once all pages are remov 104 original compressor. Once all pages are removed from an old zpool, the zpool
105 and its compressor are freed. 105 and its compressor are freed.
106 106
107 Some of the pages in zswap are same-value fill 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). T 108 page have same value or repetitive pattern). These pages include zero-filled
109 pages and they are handled differently. During 109 pages and they are handled differently. During store operation, a page is
110 checked if it is a same-value filled page befo 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 a 111 compressed length of the page is set to zero and the pattern or same-filled
112 value is stored. 112 value is stored.
113 113
>> 114 Same-value filled pages identification feature is enabled by default and can be
>> 115 disabled at boot time by setting the ``same_filled_pages_enabled`` attribute
>> 116 to 0, e.g. ``zswap.same_filled_pages_enabled=0``. It can also be enabled and
>> 117 disabled at runtime using the sysfs ``same_filled_pages_enabled``
>> 118 attribute, e.g.::
>> 119
>> 120 echo 1 > /sys/module/zswap/parameters/same_filled_pages_enabled
>> 121
>> 122 When zswap same-filled page identification is disabled at runtime, it will stop
>> 123 checking for the same-value filled pages during store operation.
>> 124 In other words, every page will be then considered non-same-value filled.
>> 125 However, the existing pages which are marked as same-value filled pages remain
>> 126 stored unchanged in zswap until they are either loaded or invalidated.
>> 127
>> 128 In some circumstances it might be advantageous to make use of just the zswap
>> 129 ability to efficiently store same-filled pages without enabling the whole
>> 130 compressed page storage.
>> 131 In this case the handling of non-same-value pages by zswap (enabled by default)
>> 132 can be disabled by setting the ``non_same_filled_pages_enabled`` attribute
>> 133 to 0, e.g. ``zswap.non_same_filled_pages_enabled=0``.
>> 134 It can also be enabled and disabled at runtime using the sysfs
>> 135 ``non_same_filled_pages_enabled`` attribute, e.g.::
>> 136
>> 137 echo 1 > /sys/module/zswap/parameters/non_same_filled_pages_enabled
>> 138
>> 139 Disabling both ``zswap.same_filled_pages_enabled`` and
>> 140 ``zswap.non_same_filled_pages_enabled`` effectively disables accepting any new
>> 141 pages by zswap.
>> 142
114 To prevent zswap from shrinking pool when zswa 143 To prevent zswap from shrinking pool when zswap is full and there's a high
115 pressure on swap (this will result in flipping 144 pressure on swap (this will result in flipping pages in and out zswap pool
116 without any real benefit but with a performanc 145 without any real benefit but with a performance drop for the system), a
117 special parameter has been introduced to imple 146 special parameter has been introduced to implement a sort of hysteresis to
118 refuse taking pages into zswap pool until it h 147 refuse taking pages into zswap pool until it has sufficient space if the limit
119 has been hit. To set the threshold at which zs 148 has been hit. To set the threshold at which zswap would start accepting pages
120 again after it became full, use the sysfs ``ac 149 again after it became full, use the sysfs ``accept_threshold_percent``
121 attribute, e. g.:: 150 attribute, e. g.::
122 151
123 echo 80 > /sys/module/zswap/parameters 152 echo 80 > /sys/module/zswap/parameters/accept_threshold_percent
124 153
125 Setting this parameter to 100 will disable the 154 Setting this parameter to 100 will disable the hysteresis.
126 155
127 Some users cannot tolerate the swapping that c 156 Some users cannot tolerate the swapping that comes with zswap store failures
128 and zswap writebacks. Swapping can be disabled 157 and zswap writebacks. Swapping can be disabled entirely (without disabling
129 zswap itself) on a cgroup-basis as follows:: !! 158 zswap itself) on a cgroup-basis as follows:
130 159
131 echo 0 > /sys/fs/cgroup/<cgroup-name>/ 160 echo 0 > /sys/fs/cgroup/<cgroup-name>/memory.zswap.writeback
132 161
133 Note that if the store failures are recurring 162 Note that if the store failures are recurring (for e.g if the pages are
134 incompressible), users can observe reclaim ine 163 incompressible), users can observe reclaim inefficiency after disabling
135 writeback (because the same pages might be rej 164 writeback (because the same pages might be rejected again and again).
136 165
137 When there is a sizable amount of cold memory 166 When there is a sizable amount of cold memory residing in the zswap pool, it
138 can be advantageous to proactively write these 167 can be advantageous to proactively write these cold pages to swap and reclaim
139 the memory for other use cases. By default, th 168 the memory for other use cases. By default, the zswap shrinker is disabled.
140 User can enable it as follows:: !! 169 User can enable it as follows:
141 170
142 echo Y > /sys/module/zswap/parameters/shrink 171 echo Y > /sys/module/zswap/parameters/shrinker_enabled
143 172
144 This can be enabled at the boot time if ``CONF 173 This can be enabled at the boot time if ``CONFIG_ZSWAP_SHRINKER_DEFAULT_ON`` is
145 selected. 174 selected.
146 175
147 A debugfs interface is provided for various st 176 A debugfs interface is provided for various statistic about pool size, number
148 of pages stored, same-value filled pages and v 177 of pages stored, same-value filled pages and various counters for the reasons
149 pages are rejected. 178 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.