[linux-2.6-block.git] / Documentation / vm / zswap.txt

Overview:

Zswap is a lightweight compressed cache for swap pages. It takes pages that are
in the process of being swapped out and attempts to compress them into a
dynamically allocated RAM-based memory pool.  zswap basically trades CPU cycles
for potentially reduced swap I/O.  This trade-off can also result in a
significant performance improvement if reads from the compressed cache are
faster than reads from a swap device.

NOTE: Zswap is a new feature as of v3.11 and interacts heavily with memory
reclaim.  This interaction has not been fully explored on the large set of
potential configurations and workloads that exist.  For this reason, zswap
is a work in progress and should be considered experimental.

Some potential benefits:
* Desktop/laptop users with limited RAM capacities can mitigate the
    performance impact of swapping.
* Overcommitted guests that share a common I/O resource can
    dramatically reduce their swap I/O pressure, avoiding heavy handed I/O
    throttling by the hypervisor. This allows more work to get done with less
    impact to the guest workload and guests sharing the I/O subsystem
* Users with SSDs as swap devices can extend the life of the device by
    drastically reducing life-shortening writes.

Zswap evicts pages from compressed cache on an LRU basis to the backing swap
device when the compressed pool reaches its size limit.  This requirement had
been identified in prior community discussions.

Zswap is disabled by default but can be enabled at boot time by setting
the "enabled" attribute to 1 at boot time. ie: zswap.enabled=1.  Zswap
can also be enabled and disabled at runtime using the sysfs interface.
An example command to enable zswap at runtime, assuming sysfs is mounted
at /sys, is:

echo 1 > /sys/modules/zswap/parameters/enabled

When zswap is disabled at runtime it will stop storing pages that are
being swapped out.  However, it will _not_ immediately write out or fault
back into memory all of the pages stored in the compressed pool.  The
pages stored in zswap will remain in the compressed pool until they are
either invalidated or faulted back into memory.  In order to force all
pages out of the compressed pool, a swapoff on the swap device(s) will
fault back into memory all swapped out pages, including those in the
compressed pool.

Design:

Zswap receives pages for compression through the Frontswap API and is able to
evict pages from its own compressed pool on an LRU basis and write them back to
the backing swap device in the case that the compressed pool is full.

Zswap makes use of zbud for the managing the compressed memory pool.  Each
allocation in zbud is not directly accessible by address.  Rather, a handle is
returned by the allocation routine and that handle must be mapped before being
accessed.  The compressed memory pool grows on demand and shrinks as compressed
pages are freed.  The pool is not preallocated.

When a swap page is passed from frontswap to zswap, zswap maintains a mapping
of the swap entry, a combination of the swap type and swap offset, to the zbud
handle that references that compressed swap page.  This mapping is achieved
with a red-black tree per swap type.  The swap offset is the search key for the
tree nodes.

During a page fault on a PTE that is a swap entry, frontswap calls the zswap
load function to decompress the page into the page allocated by the page fault
handler.

Once there are no PTEs referencing a swap page stored in zswap (i.e. the count
in the swap_map goes to 0) the swap code calls the zswap invalidate function,
via frontswap, to free the compressed entry.

Zswap seeks to be simple in its policies.  Sysfs attributes allow for one user
controlled policy:
* max_pool_percent - The maximum percentage of memory that the compressed
    pool can occupy.

Zswap allows the compressor to be selected at kernel boot time by setting the
“compressor” attribute.  The default compressor is lzo.  e.g.
zswap.compressor=deflate

A debugfs interface is provided for various statistic about pool size, number
of pages stored, and various counters for the reasons pages are rejected.
Commit	Line	Data
61b0d760 SJ	1	Overview:
	2
	3	Zswap is a lightweight compressed cache for swap pages. It takes pages that are
	4	in the process of being swapped out and attempts to compress them into a
	5	dynamically allocated RAM-based memory pool. zswap basically trades CPU cycles
	6	for potentially reduced swap I/O. This trade-off can also result in a
	7	significant performance improvement if reads from the compressed cache are
	8	faster than reads from a swap device.
	9
	10	NOTE: Zswap is a new feature as of v3.11 and interacts heavily with memory
0151e3d6	11	reclaim. This interaction has not been fully explored on the large set of
61b0d760 SJ	12	potential configurations and workloads that exist. For this reason, zswap
	13	is a work in progress and should be considered experimental.
	14
	15	Some potential benefits:
	16	* Desktop/laptop users with limited RAM capacities can mitigate the
	17	performance impact of swapping.
	18	* Overcommitted guests that share a common I/O resource can
	19	dramatically reduce their swap I/O pressure, avoiding heavy handed I/O
	20	throttling by the hypervisor. This allows more work to get done with less
	21	impact to the guest workload and guests sharing the I/O subsystem
	22	* Users with SSDs as swap devices can extend the life of the device by
	23	drastically reducing life-shortening writes.
	24
	25	Zswap evicts pages from compressed cache on an LRU basis to the backing swap
0151e3d6	26	device when the compressed pool reaches its size limit. This requirement had
61b0d760 SJ	27	been identified in prior community discussions.
61b0d760 SJ	28
c00ed16a DS	29	Zswap is disabled by default but can be enabled at boot time by setting
	30	the "enabled" attribute to 1 at boot time. ie: zswap.enabled=1. Zswap
	31	can also be enabled and disabled at runtime using the sysfs interface.
	32	An example command to enable zswap at runtime, assuming sysfs is mounted
	33	at /sys, is:
	34
	35	echo 1 > /sys/modules/zswap/parameters/enabled
	36
	37	When zswap is disabled at runtime it will stop storing pages that are
	38	being swapped out. However, it will _not_ immediately write out or fault
	39	back into memory all of the pages stored in the compressed pool. The
	40	pages stored in zswap will remain in the compressed pool until they are
	41	either invalidated or faulted back into memory. In order to force all
	42	pages out of the compressed pool, a swapoff on the swap device(s) will
	43	fault back into memory all swapped out pages, including those in the
	44	compressed pool.
61b0d760 SJ	45
	46	Design:
	47
	48	Zswap receives pages for compression through the Frontswap API and is able to
	49	evict pages from its own compressed pool on an LRU basis and write them back to
	50	the backing swap device in the case that the compressed pool is full.
	51
	52	Zswap makes use of zbud for the managing the compressed memory pool. Each
	53	allocation in zbud is not directly accessible by address. Rather, a handle is
0151e3d6	54	returned by the allocation routine and that handle must be mapped before being
61b0d760 SJ	55	accessed. The compressed memory pool grows on demand and shrinks as compressed
	56	pages are freed. The pool is not preallocated.
	57
	58	When a swap page is passed from frontswap to zswap, zswap maintains a mapping
	59	of the swap entry, a combination of the swap type and swap offset, to the zbud
	60	handle that references that compressed swap page. This mapping is achieved
	61	with a red-black tree per swap type. The swap offset is the search key for the
	62	tree nodes.
	63
	64	During a page fault on a PTE that is a swap entry, frontswap calls the zswap
	65	load function to decompress the page into the page allocated by the page fault
	66	handler.
	67
	68	Once there are no PTEs referencing a swap page stored in zswap (i.e. the count
	69	in the swap_map goes to 0) the swap code calls the zswap invalidate function,
	70	via frontswap, to free the compressed entry.
	71
	72	Zswap seeks to be simple in its policies. Sysfs attributes allow for one user
0151e3d6	73	controlled policy:
61b0d760 SJ	74	* max_pool_percent - The maximum percentage of memory that the compressed
	75	pool can occupy.
	76
	77	Zswap allows the compressor to be selected at kernel boot time by setting the
	78	“compressor” attribute. The default compressor is lzo. e.g.
	79	zswap.compressor=deflate
	80
	81	A debugfs interface is provided for various statistic about pool size, number
	82	of pages stored, and various counters for the reasons pages are rejected.