docs/vm: frontswap.txt: convert to ReST format

.. _frontswap:

=========

Frontswap

=========

Frontswap provides a "transcendent memory" interface for swap pages.

In some environments, dramatic performance savings may be obtained because

swapped pages are saved in RAM (or a RAM-like device) instead of a swap disk.

(Note, frontswap -- and cleancache (merged at 3.0) -- are the "frontends"

(Note, frontswap -- and :ref:`cleancache` (merged at 3.0) -- are the "frontends"

and the only necessary changes to the core kernel for transcendent memory;

all other supporting code -- the "backends" -- is implemented as drivers.

See the LWN.net article "Transcendent memory in a nutshell" for a detailed

overview of frontswap and related kernel parts:

https://lwn.net/Articles/454795/ )

See the LWN.net article `Transcendent memory in a nutshell`_

for a detailed overview of frontswap and related kernel parts)

.. _Transcendent memory in a nutshell: https://lwn.net/Articles/454795/

Frontswap is so named because it can be thought of as the opposite of

a "backing" store for a swap device.  The storage is assumed to be

never be obtained from frontswap.

If properly configured, monitoring of frontswap is done via debugfs in

the /sys/kernel/debug/frontswap directory.  The effectiveness of

the `/sys/kernel/debug/frontswap` directory.  The effectiveness of

frontswap can be measured (across all swap devices) with:

failed_stores	- how many store attempts have failed

loads		- how many loads were attempted (all should succeed)

succ_stores	- how many store attempts have succeeded

invalidates	- how many invalidates were attempted

``failed_stores``

	how many store attempts have failed

``loads``

	how many loads were attempted (all should succeed)

``succ_stores``

	how many store attempts have succeeded

``invalidates``

	how many invalidates were attempted

A backend implementation may provide additional metrics.

FAQ

===

1) Where's the value?

* Where's the value?

When a workload starts swapping, performance falls through the floor.

Frontswap significantly increases performance in many such workloads by

using frontswap, investigation is also underway on the use of NVM as

a memory extension technology.

2) Sure there may be performance advantages in some situations, but

* Sure there may be performance advantages in some situations, but

  what's the space/time overhead of frontswap?

If CONFIG_FRONTSWAP is disabled, every frontswap hook compiles into

backend, such as zcache, must implement policies to carefully (but

dynamically) manage memory limits to ensure this doesn't happen.

3) OK, how about a quick overview of what this frontswap patch does

* OK, how about a quick overview of what this frontswap patch does

  in terms that a kernel hacker can grok?

Let's assume that a frontswap "backend" has registered during

store" and (possibly) a "frontswap backend loads", which are presumably much

faster.

4) Can't frontswap be configured as a "special" swap device that is

* Can't frontswap be configured as a "special" swap device that is

  just higher priority than any real swap device (e.g. like zswap,

  or maybe swap-over-nbd/NFS)?

can still use frontswap but a backend for such devices must configure

some kind of "ghost" swap device and ensure that it is never used.

5) Why this weird definition about "duplicate stores"?  If a page

* Why this weird definition about "duplicate stores"?  If a page

  has been previously successfully stored, can't it always be

  successfully overwritten?

swap subsystem then writes the new data to the read swap device,

this is the correct course of action to ensure coherency.

6) What is frontswap_shrink for?

* What is frontswap_shrink for?

When the (non-frontswap) swap subsystem swaps out a page to a real

swap device, that page is only taking up low-value pre-allocated disk

this is driven using the frontswap_shrink mechanism when memory pressure

subsides.

7) Why does the frontswap patch create the new include file swapfile.h?

* Why does the frontswap patch create the new include file swapfile.h?

The frontswap code depends on some swap-subsystem-internal data

structures that have, over the years, moved back and forth between