admin-guide/device-mapper/cache.rst

8 dm-cache is a device mapper target written by Joe Thornber, Heinz
15 This device-mapper solution allows us to insert this caching at
17 a thin-provisioning pool.  Caching solutions that are integrated more
20 The target reuses the metadata library used in the thin-provisioning
23 The decision as to what data to migrate and when is left to a plug-in
35 	       Migration from slow device to fast device.
37 	       Migration from fast device to slow device.
46 Sub-devices
47 -----------
52 1. An origin device - the big, slow one.
54 2. A cache device - the small, fast one.
56 3. A small metadata device - records which blocks are in the cache,
64 ----------------
68 using block sizes of 256KB - 1024KB.  The block size must be between 64
79 ---------------------
96 block invalidates.  To enable passthrough mode the cache must be clean.
97 Passthrough mode allows a cache device to be activated without having to
102 writethrough or writeback mode while still warm.  Otherwise, the cache
104 operating mode.
108 shrinking a cache.  Shrinking the cache's fast device requires all cache
112 cache's fast device until the cache is clean.  This is of particular
113 importance if writeback mode is used.  Writethrough and passthrough
116 warm and in writeback mode during resize.
119 --------------------
131 Updating on-disk metadata
132 -------------------------
134 On-disk metadata is committed every time a FLUSH or FUA bio is written.
145 Per-block policy hints
146 ----------------------
148 Policy plug-ins can store a chunk of data per cache block.  It's up to
156 ----------------
159 need a generic way of getting and setting these.  Device-mapper
160 messages are used.  Refer to cache-policies.txt.
163 -------------------------
177 -----------
186  metadata dev     fast device holding the persistent metadata
187  cache dev	  fast device holding cached data blocks
199 		  See cache-policies.txt for details.
212    passthrough		a degraded mode useful for various cache coherency
217 			To enable passthrough mode the cache must be clean.
234 ------
243   <cache metadata mode>
277 cache metadata mode       ro if read-only, rw if read-write
279 			  In serious cases where even a read-only mode is
283 needs_check		  'needs_check' if set, '-' if not set
289 			  '-' indicates	needs_check is not set.
293 --------
296 need a generic way of getting and setting these.  Device-mapper
311 range's end value is "one past the end", meaning 5-10 expresses a range
315 invalidation of larger caches.  The cache must be in passthrough mode
318    invalidate_cblocks [<cblock>|<cblock begin>-<cblock end>]*
322    dmsetup message my_cache 0 invalidate_cblocks 2345 3456-4567 5678-6789
329 https://github.com/jthornber/device-mapper-test-suite
333   dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \
335   dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \