Documentation/admin-guide/mm/zswap.rst

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/mm/zswap.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/mm/zswap.rst
Extension
.rst
Size
6455 bytes
Lines
139
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=====
zswap
=====

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.

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.

Whether Zswap is enabled at the boot time depends on whether
the ``CONFIG_ZSWAP_DEFAULT_ON`` Kconfig option is enabled or not.
This setting can then be overridden by providing the kernel command line
``zswap.enabled=`` option, for example ``zswap.enabled=0``.
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/module/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 from the swap subsystem 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 zsmalloc for the managing the compressed memory pool.  Each
allocation in zsmalloc 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 swapout to zswap, zswap maintains a mapping of
the swap entry, a combination of the swap type and swap offset, to the zsmalloc
handle that references that compressed swap page.  This mapping is achieved
with an xarray per swap type.  The swap offset is the search key for the xarray
nodes.

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

Annotation

Implementation Notes