1 =====
2 zswap
3 =====
4
5 Overview
6 ========
7
8 Zswap is a lightweight compressed cache for sw
9 in the process of being swapped out and attemp
10 dynamically allocated RAM-based memory pool.
11 for potentially reduced swap I/O. This trade-
12 significant performance improvement if reads f
13 faster than reads from a swap device.
14
15 Some potential benefits:
16
17 * Desktop/laptop users with limited RAM capaci
18 performance impact of swapping.
19 * Overcommitted guests that share a common I/O
20 dramatically reduce their swap I/O pressure,
21 throttling by the hypervisor. This allows mo
22 impact to the guest workload and guests shar
23 * Users with SSDs as swap devices can extend t
24 drastically reducing life-shortening writes.
25
26 Zswap evicts pages from compressed cache on an
27 device when the compressed pool reaches its si
28 been identified in prior community discussions
29
30 Whether Zswap is enabled at the boot time depe
31 the ``CONFIG_ZSWAP_DEFAULT_ON`` Kconfig option
32 This setting can then be overridden by providi
33 ``zswap.enabled=`` option, for example ``zswap
34 Zswap can also be enabled and disabled at runt
35 An example command to enable zswap at runtime,
36 at ``/sys``, is::
37
38 echo 1 > /sys/module/zswap/parameters/
39
40 When zswap is disabled at runtime it will stop
41 being swapped out. However, it will _not_ imm
42 back into memory all of the pages stored in th
43 pages stored in zswap will remain in the compr
44 either invalidated or faulted back into memory
45 pages out of the compressed pool, a swapoff on
46 fault back into memory all swapped out pages,
47 compressed pool.
48
49 Design
50 ======
51
52 Zswap receives pages for compression from the
53 evict pages from its own compressed pool on an
54 the backing swap device in the case that the c
55
56 Zswap makes use of zpool for the managing the
57 allocation in zpool is not directly accessible
58 returned by the allocation routine and that ha
59 accessed. The compressed memory pool grows on
60 pages are freed. The pool is not preallocated
61 of type selected in ``CONFIG_ZSWAP_ZPOOL_DEFAU
62 but it can be overridden at boot time by setti
63 e.g. ``zswap.zpool=zbud``. It can also be chan
64 ``zpool`` attribute, e.g.::
65
66 echo zbud > /sys/module/zswap/paramete
67
68 The zbud type zpool allocates exactly 1 page t
69 means the compression ratio will always be 2:1
70 zbud pages). The zsmalloc type zpool has a mo
71 storage method, and it can achieve greater sto
72
73 When a swap page is passed from swapout to zsw
74 of the swap entry, a combination of the swap t
75 handle that references that compressed swap pa
76 with a red-black tree per swap type. The swap
77 tree nodes.
78
79 During a page fault on a PTE that is a swap en
80 zswap load function to decompress the page int
81 fault handler.
82
83 Once there are no PTEs referencing a swap page
84 in the swap_map goes to 0) the swap code calls
85 to free the compressed entry.
86
87 Zswap seeks to be simple in its policies. Sys
88 controlled policy:
89
90 * max_pool_percent - The maximum percentage of
91 pool can occupy.
92
93 The default compressor is selected in ``CONFIG
94 Kconfig option, but it can be overridden at bo
95 ``compressor`` attribute, e.g. ``zswap.compres
96 It can also be changed at runtime using the sy
97 attribute, e.g.::
98
99 echo lzo > /sys/module/zswap/parameter
100
101 When the zpool and/or compressor parameter is
102 compressed pages are not modified; they are le
103 request is made for a page in an old zpool, it
104 original compressor. Once all pages are remov
105 and its compressor are freed.
106
107 Some of the pages in zswap are same-value fill
108 page have same value or repetitive pattern). T
109 pages and they are handled differently. During
110 checked if it is a same-value filled page befo
111 compressed length of the page is set to zero a
112 value is stored.
113
114 To prevent zswap from shrinking pool when zswa
115 pressure on swap (this will result in flipping
116 without any real benefit but with a performanc
117 special parameter has been introduced to imple
118 refuse taking pages into zswap pool until it h
119 has been hit. To set the threshold at which zs
120 again after it became full, use the sysfs ``ac
121 attribute, e. g.::
122
123 echo 80 > /sys/module/zswap/parameters
124
125 Setting this parameter to 100 will disable the
126
127 Some users cannot tolerate the swapping that c
128 and zswap writebacks. Swapping can be disabled
129 zswap itself) on a cgroup-basis as follows::
130
131 echo 0 > /sys/fs/cgroup/<cgroup-name>/
132
133 Note that if the store failures are recurring
134 incompressible), users can observe reclaim ine
135 writeback (because the same pages might be rej
136
137 When there is a sizable amount of cold memory
138 can be advantageous to proactively write these
139 the memory for other use cases. By default, th
140 User can enable it as follows::
141
142 echo Y > /sys/module/zswap/parameters/shrink
143
144 This can be enabled at the boot time if ``CONF
145 selected.
146
147 A debugfs interface is provided for various st
148 of pages stored, same-value filled pages and v
149 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.