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