lwn.git/drivers/md/dm-cache-metadata.h, branch docs-mw

dm cache: prevent entering passthrough mode after unclean shutdown

2026-03-02T15:50:18+00:00

dm-cache assumes all cache blocks are dirty when it recovers from an unclean shutdown. Given that the passthrough mode doesn't handle dirty blocks, we should not load a cache in passthrough mode if it was not cleanly shut down; or we'll risk data loss while updating an actually dirty block. Also bump the target version to 2.4.0 to mark completion of passthrough mode fixes. Reproduce steps: 1. Create a writeback cache with zero migration_threshold to produce dirty blocks. dmsetup create cmeta --table "0 8192 linear /dev/sdc 0" dmsetup create cdata --table "0 131072 linear /dev/sdc 8192" dmsetup create corig --table "0 262144 linear /dev/sdc 262144" dd if=/dev/zero of=/dev/mapper/cmeta bs=4k count=1 oflag=direct dmsetup create cache --table "0 262144 cache /dev/mapper/cmeta \ /dev/mapper/cdata /dev/mapper/corig 128 2 metadata2 writeback smq \ 2 migration_threshold 0" 2. Write the first cache block dirty fio --filename=/dev/mapper/cache --name=populate --rw=write --bs=4k \ --direct=1 --size=64k 3. Ensure the number of dirty blocks is 1. This status query triggers metadata commit without flushing the dirty bitset, setting up the unclean shutdown state. dmsetup status cache | awk '{print $14}' 4. Force reboot, leaving the cache uncleanly shutdown. echo b > /proc/sysrq-trigger 5. Activate the above cache components, and verify the first data block remains dirty. dmsetup create cmeta --table "0 8192 linear /dev/sdc 0" dmsetup create cdata --table "0 131072 linear /dev/sdc 8192" dmsetup create corig --table "0 262144 linear /dev/sdc 262144" dd if=/dev/mapper/cdata of=/tmp/cb0.bin bs=64k count=1 dd if=/dev/mapper/corig of=/tmp/ob0.bin bs=64k count=1 md5sum /tmp/cb0.bin /tmp/ob0.bin # expected to be different 6. Try bringing up the cache in passthrough mode. It succeeds, while the first cache block was loaded dirty due to unclean shutdown, violates the passthrough mode's constraints. dmsetup create cache --table "0 262144 cache /dev/mapper/cmeta \ /dev/mapper/cdata /dev/mapper/corig 128 2 metadata2 passthrough smq 0" dmsetup status cache | awk '{print $14}' 7. (Optional) Demonstrate the integrity issue: invalidating the dirty block in passthrough mode doesn't write back the dirty data, causing data loss. fio --filename=/dev/mapper/cache --name=invalidate --rw=write --bs=4k \ --direct=1 --size=4k # overwrite the first 4k to trigger invalidation dmsetup remove cache dd if=/dev/mapper/corig of=/tmp/ob0new.bin bs=64k count=1 cb0sum=$(dd if=/tmp/cb0.bin bs=4k count=15 skip=1 | md5sum | \ awk '{print $1}') ob0newsum=$(dd if=/tmp/ob0new.bin bs=4k count=15 skip=1 | md5sum | \ awk '{print $1}') echo "$cb0sum, $ob0newsum" # remaining 60k should differ (data loss) Signed-off-by: Ming-Hung Tsai Signed-off-by: Mikulas Patocka

dm cache: fix dirty mapping checking in passthrough mode switching

2026-03-02T15:50:08+00:00

As mentioned in commit 9b1cc9f251af ("dm cache: share cache-metadata object across inactive and active DM tables"), dm-cache assumed table reload occurs after suspension, while LVM's table preload breaks this assumption. The dirty mapping check for passthrough mode was designed around this assumption and is performed during table creation, causing the check to fail with preload while metadata updates are ongoing. This risks loading dirty mappings into passthrough mode, resulting in data loss. Reproduce steps: 1. Create a writeback cache with zero migration_threshold to produce dirty mappings dmsetup create cmeta --table "0 8192 linear /dev/sdc 0" dmsetup create cdata --table "0 131072 linear /dev/sdc 8192" dmsetup create corig --table "0 262144 linear /dev/sdc 262144" dd if=/dev/zero of=/dev/mapper/cmeta bs=4k count=1 oflag=direct dmsetup create cache --table "0 262144 cache /dev/mapper/cmeta \ /dev/mapper/cdata /dev/mapper/corig 128 2 metadata2 writeback smq \ 2 migration_threshold 0" 2. Preload a table in passthrough mode dmsetup reload cache --table "0 262144 cache /dev/mapper/cmeta \ /dev/mapper/cdata /dev/mapper/corig 128 2 metadata2 passthrough smq 0" 3. Write to the first cache block to make it dirty fio --filename=/dev/mapper/cache --name=populate --rw=write --bs=4k \ --direct=1 --size=64k 4. Resume the inactive table. Now it's possible to load the dirty block into passthrough mode. dmsetup resume cache Fix by moving the checks to the preresume phase to support table preloading. Also remove the unused function dm_cache_metadata_all_clean. Fixes: 2ee57d587357 ("dm cache: add passthrough mode") Signed-off-by: Ming-Hung Tsai Signed-off-by: Mikulas Patocka

dm cache: Remove unused dm_cache_size

2024-11-20T10:38:04+00:00

dm_cache_size() has been unused since the original commit c6b4fcbad044 ("dm: add cache target") Remove it. Signed-off-by: Dr. David Alan Gilbert Signed-off-by: Mikulas Patocka

dm cache: Remove unused dm_cache_dump

2024-11-20T10:38:04+00:00

dm_cache_dump() has been unused since the original commit c6b4fcbad044 ("dm: add cache target") Remove it. Signed-off-by: Dr. David Alan Gilbert Signed-off-by: Mikulas Patocka

dm: change "unsigned" to "unsigned int"

2023-02-14T19:23:06+00:00

Signed-off-by: Heinz Mauelshagen Signed-off-by: Mike Snitzer

dm: add missing SPDX-License-Indentifiers

2023-02-14T19:23:06+00:00

'GPL-2.0-only' is used instead of 'GPL-2.0' because SPDX has deprecated its use. Suggested-by: John Wiele Signed-off-by: Heinz Mauelshagen Signed-off-by: Mike Snitzer

dm cache: fix typo in 2 comment blocks

2022-07-07T15:49:37+00:00

Replace neccessarily with necessarily. Signed-off-by: Steven Lung <1030steven@gmail.com> Signed-off-by: Mike Snitzer

dm cache: significant rework to leverage dm-bio-prison-v2

2017-03-07T18:28:31+00:00

The cache policy interfaces have been updated to work well with the new bio-prison v2 interface's ability to queue work immediately (promotion, demotion, etc) -- overriding benefit being reduced latency on processing IO through the cache. Previously such work would be left for the DM cache core to queue on various lists and then process in batches later -- this caused a serious delay in latency for IO driven by the cache. The background tracker code was factored out so that all cache policies can make use of it. Also, the "cleaner" policy has been removed and is now a variant of the smq policy that simply disallows migrations. Signed-off-by: Joe Thornber Signed-off-by: Mike Snitzer

dm cache metadata: add "metadata2" feature

2017-02-16T18:12:47+00:00

If "metadata2" is provided as a table argument when creating/loading a cache target a more compact metadata format, with separate dirty bits, is used. "metadata2" improves speed of shutting down a cache target. Signed-off-by: Joe Thornber Signed-off-by: Mike Snitzer

dm cache: make sure every metadata function checks fail_io

2016-03-10T22:12:12+00:00

Otherwise operations may be attempted that will only ever go on to crash (since the metadata device is either missing or unreliable if 'fail_io' is set). Signed-off-by: Joe Thornber Signed-off-by: Mike Snitzer Cc: stable@vger.kernel.org