linux/Documentation/admin-guide/device-mapper
Dongsheng Yang 1d57628ff9 dm-pcache: add persistent cache target in device-mapper
This patch introduces dm-pcache, a new DM target that places a DAX-
capable persistent-memory device in front of any slower block device and
uses it as a high-throughput, low-latency  cache.

Design highlights
-----------------
- DAX data path – data is copied directly between DRAM and the pmem
  mapping, bypassing the block layer’s overhead.

- Segmented, crash-consistent layout
  - all layout metadata are dual-replicated CRC-protected.
  - atomic kset flushes; key replay on mount guarantees cache integrity
    even after power loss.

- Striped multi-tree index
  - Multi‑tree indexing for high parallelism.
  - overlap-resolution logic ensures non-intersecting cached extents.

- Background services
  - write-back worker flushes dirty keys in order, preserving backing-device
    crash consistency. This is important for checkpoint in cloud storage.
  - garbage collector reclaims clean segments when utilisation exceeds a
    tunable threshold.

- Data integrity – optional CRC32 on cached payload; metadata always protected.

Comparison with existing block-level caches
---------------------------------------------------------------------------------------------------------------------------------
| Feature                          | pcache (this patch)             | bcache                       | dm-writecache             |
|----------------------------------|---------------------------------|------------------------------|---------------------------|
| pmem access method               | DAX                             | bio (block I/O)              | DAX                       |
| Write latency (4 K rand-write)   | ~5 µs                           | ~20 µs                       | ~5 µs                     |
| Concurrency                      | multi subtree index             | global index tree            | single tree + wc_lock     |
| IOPS (4K randwrite, 32 numjobs)  | 2.1 M                           | 352 K                        | 283 K                     |
| Read-cache support               | YES                             | YES                          | NO                        |
| Deployment                       | no re-format of backend         | backend devices must be      | no re-format of backend   |
|                                  |                                 | reformatted                  |                           |
| Write-back ordering              | log-structured;                 | no ordering guarantee        | no ordering guarantee     |
|                                  | preserves app-IO-order          |                              |                           |
| Data integrity checks            | metadata + data CRC(optional)   | metadata CRC only            | none                      |
---------------------------------------------------------------------------------------------------------------------------------

Signed-off-by: Dongsheng Yang <dongsheng.yang@linux.dev>
Signed-off-by: Mikulas Patocka <mpatocka@redhat.com>
2025-08-25 15:25:29 +02:00
..
cache-policies.rst Documentation: admin-guide: correct spelling 2023-02-02 11:04:42 -07:00
cache.rst
delay.rst docs: device-mapper: fixed spelling mistakes in documentation 2025-08-19 11:12:50 +02:00
dm-clone.rst
dm-crypt.rst dm-crypt: Document integrity_key_size option. 2025-02-03 14:10:10 +01:00
dm-dust.rst
dm-ebs.rst Documentation: admin-guide: correct spelling 2023-02-02 11:04:42 -07:00
dm-flakey.rst dm flakey: introduce random_read_corrupt and random_write_corrupt options 2023-06-16 18:24:13 -04:00
dm-ima.rst
dm-init.rst dm init: add dm-mod.waitfor to wait for asynchronously probed block devices 2022-12-02 17:37:45 -05:00
dm-integrity.rst dm-integrity: Document Inline mode for storing integrity data 2025-02-03 14:10:10 +01:00
dm-io.rst
dm-log.rst
dm-pcache.rst dm-pcache: add persistent cache target in device-mapper 2025-08-25 15:25:29 +02:00
dm-queue-length.rst
dm-raid.rst
dm-service-time.rst
dm-uevent.rst
dm-zoned.rst Documentation: admin-guide: correct spelling 2023-02-02 11:04:42 -07:00
era.rst
index.rst dm-pcache: add persistent cache target in device-mapper 2025-08-25 15:25:29 +02:00
kcopyd.rst
linear.rst
log-writes.rst
persistent-data.rst
snapshot.rst
statistics.rst
striped.rst
switch.rst
thin-provisioning.rst dm-thin: update the documentation 2025-07-31 15:43:30 +02:00
unstriped.rst Documentation: admin-guide: correct spelling 2023-02-02 11:04:42 -07:00
vdo-design.rst docs: device-mapper: fix typos in delay.rst and vdo-design.rst 2025-08-19 11:12:49 +02:00
vdo.rst dm-vdo: Promote dm-vdo title to title heading 2025-08-19 11:12:50 +02:00
verity.rst dm-verity: support block number limits for different ioprio classes 2025-03-28 11:32:55 +01:00
writecache.rst dm writecache: count number of blocks discarded, not number of discard bios 2022-07-14 15:54:46 -04:00
zero.rst