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
38Zswap is disabled by default but can be enabled at boot time by setting
39the ``enabled`` attribute to 1 at boot time. ie: ``zswap.enabled=1``.  Zswap
40can also be enabled and disabled at runtime using the sysfs interface.
41An example command to enable zswap at runtime, assuming sysfs is mounted
42at ``/sys``, is::
43
44	echo 1 > /sys/module/zswap/parameters/enabled
45
46When zswap is disabled at runtime it will stop storing pages that are
47being swapped out.  However, it will _not_ immediately write out or fault
48back into memory all of the pages stored in the compressed pool.  The
49pages stored in zswap will remain in the compressed pool until they are
50either invalidated or faulted back into memory.  In order to force all
51pages out of the compressed pool, a swapoff on the swap device(s) will
52fault back into memory all swapped out pages, including those in the
53compressed pool.
54
55Design
56======
57
58Zswap receives pages for compression through the Frontswap API and is able to
59evict pages from its own compressed pool on an LRU basis and write them back to
60the backing swap device in the case that the compressed pool is full.
61
62Zswap makes use of zpool for the managing the compressed memory pool.  Each
63allocation in zpool is not directly accessible by address.  Rather, a handle is
64returned by the allocation routine and that handle must be mapped before being
65accessed.  The compressed memory pool grows on demand and shrinks as compressed
66pages are freed.  The pool is not preallocated.  By default, a zpool
67of type zbud is created, but it can be selected at boot time by
68setting the ``zpool`` attribute, e.g. ``zswap.zpool=zbud``. It can
69also be changed at runtime using the sysfs ``zpool`` attribute, e.g.::
70
71	echo zbud > /sys/module/zswap/parameters/zpool
72
73The zbud type zpool allocates exactly 1 page to store 2 compressed pages, which
74means the compression ratio will always be 2:1 or worse (because of half-full
75zbud pages).  The zsmalloc type zpool has a more complex compressed page
76storage method, and it can achieve greater storage densities.  However,
77zsmalloc does not implement compressed page eviction, so once zswap fills it
78cannot evict the oldest page, it can only reject new pages.
79
80When a swap page is passed from frontswap to zswap, zswap maintains a mapping
81of the swap entry, a combination of the swap type and swap offset, to the zpool
82handle that references that compressed swap page.  This mapping is achieved
83with a red-black tree per swap type.  The swap offset is the search key for the
84tree nodes.
85
86During a page fault on a PTE that is a swap entry, frontswap calls the zswap
87load function to decompress the page into the page allocated by the page fault
88handler.
89
90Once there are no PTEs referencing a swap page stored in zswap (i.e. the count
91in the swap_map goes to 0) the swap code calls the zswap invalidate function,
92via frontswap, to free the compressed entry.
93
94Zswap seeks to be simple in its policies.  Sysfs attributes allow for one user
95controlled policy:
96
97* max_pool_percent - The maximum percentage of memory that the compressed
98  pool can occupy.
99
100The default compressor is lzo, but it can be selected at boot time by
101setting the ``compressor`` attribute, e.g. ``zswap.compressor=lzo``.
102It can also be changed at runtime using the sysfs "compressor"
103attribute, e.g.::
104
105	echo lzo > /sys/module/zswap/parameters/compressor
106
107When the zpool and/or compressor parameter is changed at runtime, any existing
108compressed pages are not modified; they are left in their own zpool.  When a
109request is made for a page in an old zpool, it is uncompressed using its
110original compressor.  Once all pages are removed from an old zpool, the zpool
111and its compressor are freed.
112
113Some of the pages in zswap are same-value filled pages (i.e. contents of the
114page have same value or repetitive pattern). These pages include zero-filled
115pages and they are handled differently. During store operation, a page is
116checked if it is a same-value filled page before compressing it. If true, the
117compressed length of the page is set to zero and the pattern or same-filled
118value is stored.
119
120Same-value filled pages identification feature is enabled by default and can be
121disabled at boot time by setting the ``same_filled_pages_enabled`` attribute
122to 0, e.g. ``zswap.same_filled_pages_enabled=0``. It can also be enabled and
123disabled at runtime using the sysfs ``same_filled_pages_enabled``
124attribute, e.g.::
125
126	echo 1 > /sys/module/zswap/parameters/same_filled_pages_enabled
127
128When zswap same-filled page identification is disabled at runtime, it will stop
129checking for the same-value filled pages during store operation. However, the
130existing pages which are marked as same-value filled pages remain stored
131unchanged in zswap until they are either loaded or invalidated.
132
133A debugfs interface is provided for various statistic about pool size, number
134of pages stored, same-value filled pages and various counters for the reasons
135pages are rejected.
136