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