sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget3/translations/zh_CN/admin-guide/device-mapper/cachemodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/zh_TW/admin-guide/device-mapper/cachemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/it_IT/admin-guide/device-mapper/cachemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/ja_JP/admin-guide/device-mapper/cachemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/ko_KR/admin-guide/device-mapper/cachemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/sp_SP/admin-guide/device-mapper/cachemodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hCacheh]hCache}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhM/var/lib/git/docbuild/linux/Documentation/admin-guide/device-mapper/cache.rsthKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(h`dm-cache is a device mapper target written by Joe Thornber, Heinz Mauelshagen, and Mike Snitzer.h]h`dm-cache is a device mapper target written by Joe Thornber, Heinz Mauelshagen, and Mike Snitzer.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hIt aims to improve performance of a block device (eg, a spindle) by dynamically migrating some of its data to a faster, smaller device (eg, an SSD).h]hIt aims to improve performance of a block device (eg, a spindle) by dynamically migrating some of its data to a faster, smaller device (eg, an SSD).}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hXThis device-mapper solution allows us to insert this caching at different levels of the dm stack, for instance above the data device for a thin-provisioning pool. Caching solutions that are integrated more closely with the virtual memory system should give better performance.h]hXThis device-mapper solution allows us to insert this caching at different levels of the dm stack, for instance above the data device for a thin-provisioning pool. Caching solutions that are integrated more closely with the virtual memory system should give better performance.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hMThe target reuses the metadata library used in the thin-provisioning library.h]hMThe target reuses the metadata library used in the thin-provisioning library.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hThe decision as to what data to migrate and when is left to a plug-in policy module. Several of these have been written as we experiment, and we hope other people will contribute others for specific io scenarios (eg. a vm image server).h]hThe decision as to what data to migrate and when is left to a plug-in policy module. Several of these have been written as we experiment, and we hope other people will contribute others for specific io scenarios (eg. a vm image server).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hGlossaryh]hGlossary}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh block_quote)}(hMigration Movement of the primary copy of a logical block from one device to the other. Promotion Migration from slow device to fast device. Demotion Migration from fast device to slow device. h]hdefinition_list)}(hhh](hdefinition_list_item)}(hWMigration Movement of the primary copy of a logical block from one device to the other.h](hterm)}(h Migrationh]h Migration}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1j:hhhK hj6ubh definition)}(hhh]h)}(hMMovement of the primary copy of a logical block from one device to the other.h]hMMovement of the primary copy of a logical block from one device to the other.}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjLubah}(h]h ]h"]h$]h&]uh1jJhj6ubeh}(h]h ]h"]h$]h&]uh1j4hhhK hj1ubj5)}(h4Promotion Migration from slow device to fast device.h](j;)}(h Promotionh]h Promotion}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1j:hhhK"hjiubjK)}(hhh]h)}(h*Migration from slow device to fast device.h]h*Migration from slow device to fast device.}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK#hj{ubah}(h]h ]h"]h$]h&]uh1jJhjiubeh}(h]h ]h"]h$]h&]uh1j4hhhK"hj1ubj5)}(h4Demotion Migration from fast device to slow device. h](j;)}(hDemotionh]hDemotion}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j:hhhK%hjubjK)}(hhh]h)}(h*Migration from fast device to slow device.h]h*Migration from fast device to slow device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK%hjubah}(h]h ]h"]h$]h&]uh1jJhjubeh}(h]h ]h"]h$]h&]uh1j4hhhK%hj1ubeh}(h]h ]h"]h$]h&]uh1j/hj+ubah}(h]h ]h"]h$]h&]uh1j)hhhKhjhhubh)}(hThe origin device always contains a copy of the logical block, which may be out of date or kept in sync with the copy on the cache device (depending on policy).h]hThe origin device always contains a copy of the logical block, which may be out of date or kept in sync with the copy on the cache device (depending on policy).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK'hjhhubeh}(h]glossaryah ]h"]glossaryah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hDesignh]hDesign}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK,ubh)}(hhh](h)}(h Sub-devicesh]h Sub-devices}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK/ubh)}(hfThe target is constructed by passing three devices to it (along with other parameters detailed later):h]hfThe target is constructed by passing three devices to it (along with other parameters detailed later):}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hjhhubhenumerated_list)}(hhh](h list_item)}(h&An origin device - the big, slow one. h]h)}(h%An origin device - the big, slow one.h]h%An origin device - the big, slow one.}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK4hj ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h&A cache device - the small, fast one. h]h)}(h%A cache device - the small, fast one.h]h%A cache device - the small, fast one.}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK6hj8ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXiA small metadata device - records which blocks are in the cache, which are dirty, and extra hints for use by the policy object. This information could be put on the cache device, but having it separate allows the volume manager to configure it differently, e.g. as a mirror for extra robustness. This metadata device may only be used by a single cache device. h]h)}(hXhA small metadata device - records which blocks are in the cache, which are dirty, and extra hints for use by the policy object. This information could be put on the cache device, but having it separate allows the volume manager to configure it differently, e.g. as a mirror for extra robustness. This metadata device may only be used by a single cache device.h]hXhA small metadata device - records which blocks are in the cache, which are dirty, and extra hints for use by the policy object. This information could be put on the cache device, but having it separate allows the volume manager to configure it differently, e.g. as a mirror for extra robustness. This metadata device may only be used by a single cache device.}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK8hjPubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jhjhhhhhK4ubeh}(h] sub-devicesah ]h"] sub-devicesah$]h&]uh1hhjhhhhhK/ubh)}(hhh](h)}(hFixed block sizeh]hFixed block size}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj{hhhhhK@ubh)}(hX#The origin is divided up into blocks of a fixed size. This block size is configurable when you first create the cache. Typically we've been using block sizes of 256KB - 1024KB. The block size must be between 64 sectors (32KB) and 2097152 sectors (1GB) and a multiple of 64 sectors (32KB).h]hX%The origin is divided up into blocks of a fixed size. This block size is configurable when you first create the cache. Typically we’ve been using block sizes of 256KB - 1024KB. The block size must be between 64 sectors (32KB) and 2097152 sectors (1GB) and a multiple of 64 sectors (32KB).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKBhj{hhubh)}(hXuHaving a fixed block size simplifies the target a lot. But it is something of a compromise. For instance, a small part of a block may be getting hit a lot, yet the whole block will be promoted to the cache. So large block sizes are bad because they waste cache space. And small block sizes are bad because they increase the amount of metadata (both in core and on disk).h]hXuHaving a fixed block size simplifies the target a lot. But it is something of a compromise. For instance, a small part of a block may be getting hit a lot, yet the whole block will be promoted to the cache. So large block sizes are bad because they waste cache space. And small block sizes are bad because they increase the amount of metadata (both in core and on disk).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKGhj{hhubeh}(h]fixed-block-sizeah ]h"]fixed block sizeah$]h&]uh1hhjhhhhhK@ubh)}(hhh](h)}(hCache operating modesh]hCache operating modes}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKOubh)}(hMThe cache has three operating modes: writeback, writethrough and passthrough.h]hMThe cache has three operating modes: writeback, writethrough and passthrough.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKQhjhhubh)}(hIf writeback, the default, is selected then a write to a block that is cached will go only to the cache and the block will be marked dirty in the metadata.h]hIf writeback, the default, is selected then a write to a block that is cached will go only to the cache and the block will be marked dirty in the metadata.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThjhhubh)}(hIf writethrough is selected then a write to a cached block will not complete until it has hit both the origin and cache devices. Clean blocks should remain clean.h]hIf writethrough is selected then a write to a cached block will not complete until it has hit both the origin and cache devices. Clean blocks should remain clean.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhjhhubh)}(hXSIf passthrough is selected, useful when the cache contents are not known to be coherent with the origin device, then all reads are served from the origin device (all reads miss the cache) and all writes are forwarded to the origin device; additionally, write hits cause cache block invalidates. To enable passthrough mode the cache must be clean. Passthrough mode allows a cache device to be activated without having to worry about coherency. Coherency that exists is maintained, although the cache will gradually cool as writes take place. If the coherency of the cache can later be verified, or established through use of the "invalidate_cblocks" message, the cache device can be transitioned to writethrough or writeback mode while still warm. Otherwise, the cache contents can be discarded prior to transitioning to the desired operating mode.h]hXWIf passthrough is selected, useful when the cache contents are not known to be coherent with the origin device, then all reads are served from the origin device (all reads miss the cache) and all writes are forwarded to the origin device; additionally, write hits cause cache block invalidates. To enable passthrough mode the cache must be clean. Passthrough mode allows a cache device to be activated without having to worry about coherency. Coherency that exists is maintained, although the cache will gradually cool as writes take place. If the coherency of the cache can later be verified, or established through use of the “invalidate_cblocks” message, the cache device can be transitioned to writethrough or writeback mode while still warm. Otherwise, the cache contents can be discarded prior to transitioning to the desired operating mode.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK\hjhhubh)}(hXA simple cleaner policy is provided, which will clean (write back) all dirty blocks in a cache. Useful for decommissioning a cache or when shrinking a cache. Shrinking the cache's fast device requires all cache blocks, in the area of the cache being removed, to be clean. If the area being removed from the cache still contains dirty blocks the resize will fail. Care must be taken to never reduce the volume used for the cache's fast device until the cache is clean. This is of particular importance if writeback mode is used. Writethrough and passthrough modes already maintain a clean cache. Future support to partially clean the cache, above a specified threshold, will allow for keeping the cache warm and in writeback mode during resize.h]hXA simple cleaner policy is provided, which will clean (write back) all dirty blocks in a cache. Useful for decommissioning a cache or when shrinking a cache. Shrinking the cache’s fast device requires all cache blocks, in the area of the cache being removed, to be clean. If the area being removed from the cache still contains dirty blocks the resize will fail. Care must be taken to never reduce the volume used for the cache’s fast device until the cache is clean. This is of particular importance if writeback mode is used. Writethrough and passthrough modes already maintain a clean cache. Future support to partially clean the cache, above a specified threshold, will allow for keeping the cache warm and in writeback mode during resize.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjhhubeh}(h]cache-operating-modesah ]h"]cache operating modesah$]h&]uh1hhjhhhhhKOubh)}(hhh](h)}(hMigration throttlingh]hMigration throttling}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKwubh)}(hXLMigrating data between the origin and cache device uses bandwidth. The user can set a throttle to prevent more than a certain amount of migration occurring at any one time. Currently we're not taking any account of normal io traffic going to the devices. More work needs doing here to avoid migrating during those peak io moments.h]hXNMigrating data between the origin and cache device uses bandwidth. The user can set a throttle to prevent more than a certain amount of migration occurring at any one time. Currently we’re not taking any account of normal io traffic going to the devices. More work needs doing here to avoid migrating during those peak io moments.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKyhjhhubh)}(hFor the time being, a message "migration_threshold <#sectors>" can be used to set the maximum number of sectors being migrated, the default being 2048 sectors (1MB).h]hFor the time being, a message “migration_threshold <#sectors>” can be used to set the maximum number of sectors being migrated, the default being 2048 sectors (1MB).}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]migration-throttlingah ]h"]migration throttlingah$]h&]uh1hhjhhhhhKwubh)}(hhh](h)}(hUpdating on-disk metadatah]hUpdating on-disk metadata}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjDhhhhhKubh)}(hXROn-disk metadata is committed every time a FLUSH or FUA bio is written. If no such requests are made then commits will occur every second. This means the cache behaves like a physical disk that has a volatile write cache. If power is lost you may lose some recent writes. The metadata should always be consistent in spite of any crash.h]hXROn-disk metadata is committed every time a FLUSH or FUA bio is written. If no such requests are made then commits will occur every second. This means the cache behaves like a physical disk that has a volatile write cache. If power is lost you may lose some recent writes. The metadata should always be consistent in spite of any crash.}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjDhhubh)}(hXThe 'dirty' state for a cache block changes far too frequently for us to keep updating it on the fly. So we treat it as a hint. In normal operation it will be written when the dm device is suspended. If the system crashes all cache blocks will be assumed dirty when restarted.h]hXThe ‘dirty’ state for a cache block changes far too frequently for us to keep updating it on the fly. So we treat it as a hint. In normal operation it will be written when the dm device is suspended. If the system crashes all cache blocks will be assumed dirty when restarted.}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjDhhubeh}(h]updating-on-disk-metadataah ]h"]updating on-disk metadataah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hPer-block policy hintsh]hPer-block policy hints}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjyhhhhhKubh)}(hPolicy plug-ins can store a chunk of data per cache block. It's up to the policy how big this chunk is, but it should be kept small. Like the dirty flags this data is lost if there's a crash so a safe fallback value should always be possible.h]hPolicy plug-ins can store a chunk of data per cache block. It’s up to the policy how big this chunk is, but it should be kept small. Like the dirty flags this data is lost if there’s a crash so a safe fallback value should always be possible.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjyhhubh)}(h1Policy hints affect performance, not correctness.h]h1Policy hints affect performance, not correctness.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjyhhubeh}(h]per-block-policy-hintsah ]h"]per-block policy hintsah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hPolicy messagingh]hPolicy messaging}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hPolicies will have different tunables, specific to each one, so we need a generic way of getting and setting these. Device-mapper messages are used. Refer to cache-policies.txt.h]hPolicies will have different tunables, specific to each one, so we need a generic way of getting and setting these. Device-mapper messages are used. Refer to cache-policies.txt.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]policy-messagingah ]h"]policy messagingah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hDiscard bitset resolutionh]hDiscard bitset resolution}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXWe can avoid copying data during migration if we know the block has been discarded. A prime example of this is when mkfs discards the whole block device. We store a bitset tracking the discard state of blocks. However, we allow this bitset to have a different block size from the cache blocks. This is because we need to track the discard state for all of the origin device (compare with the dirty bitset which is just for the smaller cache device).h]hXWe can avoid copying data during migration if we know the block has been discarded. A prime example of this is when mkfs discards the whole block device. We store a bitset tracking the discard state of blocks. However, we allow this bitset to have a different block size from the cache blocks. This is because we need to track the discard state for all of the origin device (compare with the dirty bitset which is just for the smaller cache device).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]discard-bitset-resolutionah ]h"]discard bitset resolutionah$]h&]uh1hhjhhhhhKubeh}(h]designah ]h"]designah$]h&]uh1hhhhhhhhK,ubh)}(hhh](h)}(hTarget interfaceh]hTarget interface}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h Constructorh]h Constructor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubj*)}(hX :: cache <#feature args> []* <#policy args> [policy args]* ================ ======================================================= metadata dev fast device holding the persistent metadata cache dev fast device holding cached data blocks origin dev slow device holding original data blocks block size cache unit size in sectors #feature args number of feature arguments passed feature args writethrough or passthrough (The default is writeback.) policy the replacement policy to use #policy args an even number of arguments corresponding to key/value pairs passed to the policy policy args key/value pairs passed to the policy E.g. 'sequential_threshold 1024' See cache-policies.txt for details. ================ ======================================================= h](j*)}(h:: cache <#feature args> []* <#policy args> [policy args]* h]h literal_block)}(hcache <#feature args> []* <#policy args> [policy args]*h]hcache <#feature args> []* <#policy args> [policy args]*}hj0sbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1j.hhhKhj*ubah}(h]h ]h"]h$]h&]uh1j)hhhKhj&ubhtable)}(hhh]htgroup)}(hhh](hcolspec)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jPhjMubjQ)}(hhh]h}(h]h ]h"]h$]h&]colwidthK7uh1jPhjMubhtbody)}(hhh](hrow)}(hhh](hentry)}(hhh]h)}(h metadata devh]h metadata dev}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjrubah}(h]h ]h"]h$]h&]uh1jphjmubjq)}(hhh]h)}(h+fast device holding the persistent metadatah]h+fast device holding the persistent metadata}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjmubeh}(h]h ]h"]h$]h&]uh1jkhjhubjl)}(hhh](jq)}(hhh]h)}(h cache devh]h cache dev}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(h&fast device holding cached data blocksh]h&fast device holding cached data blocks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjhubjl)}(hhh](jq)}(hhh]h)}(h origin devh]h origin dev}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(h(slow device holding original data blocksh]h(slow device holding original data blocks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjhubjl)}(hhh](jq)}(hhh]h)}(h block sizeh]h block size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(hcache unit size in sectorsh]hcache unit size in sectors}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj.ubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjhubjl)}(hhh](jq)}(hhh]h)}(h #feature argsh]h #feature args}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjNubah}(h]h ]h"]h$]h&]uh1jphjKubjq)}(hhh]h)}(h"number of feature arguments passedh]h"number of feature arguments passed}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjeubah}(h]h ]h"]h$]h&]uh1jphjKubeh}(h]h ]h"]h$]h&]uh1jkhjhubjl)}(hhh](jq)}(hhh]h)}(h feature argsh]h feature args}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(h7writethrough or passthrough (The default is writeback.)h]h7writethrough or passthrough (The default is writeback.)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjhubjl)}(hhh](jq)}(hhh]h)}(hpolicyh]hpolicy}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(hthe replacement policy to useh]hthe replacement policy to use}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjhubjl)}(hhh](jq)}(hhh]h)}(h #policy argsh]h #policy args}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(hQan even number of arguments corresponding to key/value pairs passed to the policyh]hQan even number of arguments corresponding to key/value pairs passed to the policy}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjhubjl)}(hhh](jq)}(hhh]h)}(h policy argsh]h policy args}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj*ubah}(h]h ]h"]h$]h&]uh1jphj'ubjq)}(hhh]h)}(hikey/value pairs passed to the policy E.g. 'sequential_threshold 1024' See cache-policies.txt for details.h]hmkey/value pairs passed to the policy E.g. ‘sequential_threshold 1024’ See cache-policies.txt for details.}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjAubah}(h]h ]h"]h$]h&]uh1jphj'ubeh}(h]h ]h"]h$]h&]uh1jkhjhubeh}(h]h ]h"]h$]h&]uh1jfhjMubeh}(h]h ]h"]h$]h&]colsKuh1jKhjHubah}(h]h ]h"]h$]h&]uh1jFhj&ubeh}(h]h ]h"]h$]h&]uh1j)hhhKhjhhubh)}(hOptional feature arguments are:h]hOptional feature arguments are:}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj*)}(hX==================== ======================================================== writethrough write through caching that prohibits cache block content from being different from origin block content. Without this argument, the default behaviour is to write back cache block contents later for performance reasons, so they may differ from the corresponding origin blocks. passthrough a degraded mode useful for various cache coherency situations (e.g., rolling back snapshots of underlying storage). Reads and writes always go to the origin. If a write goes to a cached origin block, then the cache block is invalidated. To enable passthrough mode the cache must be clean. metadata2 use version 2 of the metadata. This stores the dirty bits in a separate btree, which improves speed of shutting down the cache. no_discard_passdown disable passing down discards from the cache to the origin's data device. ==================== ======================================================== h]jG)}(hhh]jL)}(hhh](jQ)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jPhjubjQ)}(hhh]h}(h]h ]h"]h$]h&]colwidthK8uh1jPhjubjg)}(hhh](jl)}(hhh](jq)}(hhh]h)}(h writethroughh]h writethrough}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(hXwrite through caching that prohibits cache block content from being different from origin block content. Without this argument, the default behaviour is to write back cache block contents later for performance reasons, so they may differ from the corresponding origin blocks.h]hXwrite through caching that prohibits cache block content from being different from origin block content. Without this argument, the default behaviour is to write back cache block contents later for performance reasons, so they may differ from the corresponding origin blocks.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h passthroughh]h passthrough}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(hX(a degraded mode useful for various cache coherency situations (e.g., rolling back snapshots of underlying storage). Reads and writes always go to the origin. If a write goes to a cached origin block, then the cache block is invalidated. To enable passthrough mode the cache must be clean.h]hX(a degraded mode useful for various cache coherency situations (e.g., rolling back snapshots of underlying storage). Reads and writes always go to the origin. If a write goes to a cached origin block, then the cache block is invalidated. To enable passthrough mode the cache must be clean.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h metadata2h]h metadata2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(huse version 2 of the metadata. This stores the dirty bits in a separate btree, which improves speed of shutting down the cache.h]huse version 2 of the metadata. This stores the dirty bits in a separate btree, which improves speed of shutting down the cache.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj.ubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(hno_discard_passdownh]hno_discard_passdown}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjNubah}(h]h ]h"]h$]h&]uh1jphjKubjq)}(hhh]h)}(hIdisable passing down discards from the cache to the origin's data device.h]hKdisable passing down discards from the cache to the origin’s data device.}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjeubah}(h]h ]h"]h$]h&]uh1jphjKubeh}(h]h ]h"]h$]h&]uh1jkhjubeh}(h]h ]h"]h$]h&]uh1jfhjubeh}(h]h ]h"]h$]h&]colsKuh1jKhjubah}(h]h ]h"]h$]h&]uh1jFhjubah}(h]h ]h"]h$]h&]uh1j)hhhKhjhhubh)}(hA policy called 'default' is always registered. This is an alias for the policy we currently think is giving best all round performance.h]hA policy called ‘default’ is always registered. This is an alias for the policy we currently think is giving best all round performance.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hAs the default policy could vary between kernels, if you are relying on the characteristics of a specific policy, always request it by name.h]hAs the default policy could vary between kernels, if you are relying on the characteristics of a specific policy, always request it by name.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] constructorah ]h"] constructorah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hStatush]hStatus}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubj/)}(hXV <#used metadata blocks>/<#total metadata blocks> <#used cache blocks>/<#total cache blocks> <#read hits> <#read misses> <#write hits> <#write misses> <#demotions> <#promotions> <#dirty> <#features> * <#core args> * <#policy args> * h]hXV <#used metadata blocks>/<#total metadata blocks> <#used cache blocks>/<#total cache blocks> <#read hits> <#read misses> <#write hits> <#write misses> <#demotions> <#promotions> <#dirty> <#features> * <#core args> * <#policy args> * }hjsbah}(h]h ]h"]h$]h&]j>j?uh1j.hhhKhjhhubjG)}(hhh]jL)}(hhh](jQ)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jPhjubjQ)}(hhh]h}(h]h ]h"]h$]h&]colwidthK5uh1jPhjubjg)}(hhh](jl)}(hhh](jq)}(hhh]h)}(hmetadata block sizeh]hmetadata block size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(h3Fixed block size for each metadata block in sectorsh]h3Fixed block size for each metadata block in sectors}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h#used metadata blocksh]h#used metadata blocks}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj5ubah}(h]h ]h"]h$]h&]uh1jphj2ubjq)}(hhh]h)}(hNumber of metadata blocks usedh]hNumber of metadata blocks used}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjLubah}(h]h ]h"]h$]h&]uh1jphj2ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h#total metadata blocksh]h#total metadata blocks}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjlubah}(h]h ]h"]h$]h&]uh1jphjiubjq)}(hhh]h)}(hTotal number of metadata blocksh]hTotal number of metadata blocks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjiubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(hcache block sizeh]hcache block size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(h7Configurable block size for the cache device in sectorsh]h7Configurable block size for the cache device in sectors}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h#used cache blocksh]h#used cache blocks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubjq)}(hhh]h)}(h&Number of blocks resident in the cacheh]h&Number of blocks resident in the cache}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jphjubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h#total cache blocksh]h#total cache blocks}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jphj ubjq)}(hhh]h)}(hTotal number of cache blocksh]hTotal number of cache blocks}(hj+ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj( ubah}(h]h ]h"]h$]h&]uh1jphj ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h #read hitsh]h #read hits}(hjK hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjH ubah}(h]h ]h"]h$]h&]uh1jphjE ubjq)}(hhh]h)}(h7Number of times a READ bio has been mapped to the cacheh]h7Number of times a READ bio has been mapped to the cache}(hjb hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj_ ubah}(h]h ]h"]h$]h&]uh1jphjE ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h #read missesh]h #read misses}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jphj| ubjq)}(hhh]h)}(h8Number of times a READ bio has been mapped to the originh]h8Number of times a READ bio has been mapped to the origin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jphj| ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h #write hitsh]h #write hits}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jphj ubjq)}(hhh]h)}(h8Number of times a WRITE bio has been mapped to the cacheh]h8Number of times a WRITE bio has been mapped to the cache}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jphj ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h #write missesh]h #write misses}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jphj ubjq)}(hhh]h)}(h9Number of times a WRITE bio has been mapped to the originh]h9Number of times a WRITE bio has been mapped to the origin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jphj ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h #demotionsh]h #demotions}(hj' hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj$ ubah}(h]h ]h"]h$]h&]uh1jphj! ubjq)}(hhh]h)}(h7Number of times a block has been removed from the cacheh]h7Number of times a block has been removed from the cache}(hj> hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj; ubah}(h]h ]h"]h$]h&]uh1jphj! ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h #promotionsh]h #promotions}(hj^ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj[ ubah}(h]h ]h"]h$]h&]uh1jphjX ubjq)}(hhh]h)}(h3Number of times a block has been moved to the cacheh]h3Number of times a block has been moved to the cache}(hju hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjr ubah}(h]h ]h"]h$]h&]uh1jphjX ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h#dirtyh]h#dirty}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj ubah}(h]h ]h"]h$]h&]uh1jphj ubjq)}(hhh]h)}(h9Number of blocks in the cache that differ from the originh]h9Number of blocks in the cache that differ from the origin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj ubah}(h]h ]h"]h$]h&]uh1jphj ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h #feature argsh]h #feature args}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj ubah}(h]h ]h"]h$]h&]uh1jphj ubjq)}(hhh]h)}(h Number of feature args to followh]h Number of feature args to follow}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj ubah}(h]h ]h"]h$]h&]uh1jphj ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h feature argsh]h feature args}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jphj ubjq)}(hhh]h)}(h'writethrough' (optional)h]h‘writethrough’ (optional)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jphj ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h #core argsh]h #core args}(hj: hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj7 ubah}(h]h ]h"]h$]h&]uh1jphj4 ubjq)}(hhh]h)}(h'Number of core arguments (must be even)h]h'Number of core arguments (must be even)}(hjQ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjN ubah}(h]h ]h"]h$]h&]uh1jphj4 ubeh}(h]h ]h"]h$]h&]uh1jkhjubjl)}(hhh](jq)}(hhh]h)}(h core argsh]h core args}(hjq hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjn ubah}(h]h ]h"]h$]h&]uh1jphjk ubjq)}(hhh]h)}(h h]h }hj sbah}(h]h ]h"]h$]h&]j>j?uh1j.hhhM-hj hhubh)}(hE.g.::h]hE.g.:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM/hj hhubj/)}(h4dmsetup message my_cache 0 sequential_threshold 1024h]h4dmsetup message my_cache 0 sequential_threshold 1024}hj' sbah}(h]h ]h"]h$]h&]j>j?uh1j.hhhM1hj hhubh)}(hXCInvalidation is removing an entry from the cache without writing it back. Cache blocks can be invalidated via the invalidate_cblocks message, which takes an arbitrary number of cblock ranges. Each cblock range's end value is "one past the end", meaning 5-10 expresses a range of values from 5 to 9. Each cblock must be expressed as a decimal value, in the future a variant message that takes cblock ranges expressed in hexadecimal may be needed to better support efficient invalidation of larger caches. The cache must be in passthrough mode when invalidate_cblocks is used::h]hXHInvalidation is removing an entry from the cache without writing it back. Cache blocks can be invalidated via the invalidate_cblocks message, which takes an arbitrary number of cblock ranges. Each cblock range’s end value is “one past the end”, meaning 5-10 expresses a range of values from 5 to 9. Each cblock must be expressed as a decimal value, in the future a variant message that takes cblock ranges expressed in hexadecimal may be needed to better support efficient invalidation of larger caches. The cache must be in passthrough mode when invalidate_cblocks is used:}(hj5 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM4hj hhubj/)}(h:invalidate_cblocks [|-]*h]h:invalidate_cblocks [|-]*}hjC sbah}(h]h ]h"]h$]h&]j>j?uh1j.hhhM>hj hhubh)}(hE.g.::h]hE.g.:}(hjQ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM@hj hhubj/)}(hFdmsetup message my_cache 0 invalidate_cblocks 2345 3456-4567 5678-6789h]hFdmsetup message my_cache 0 invalidate_cblocks 2345 3456-4567 5678-6789}hj_ sbah}(h]h ]h"]h$]h&]j>j?uh1j.hhhMBhj hhubeh}(h]messagesah ]h"]messagesah$]h&]uh1hhjhhhhhM%ubeh}(h]target-interfaceah ]h"]target interfaceah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hExamplesh]hExamples}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj} hhhhhMEubh)}(h!The test suite can be found here:h]h!The test suite can be found here:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMGhj} hhubh)}(h5https://github.com/jthornber/device-mapper-test-suiteh]h reference)}(hj h]h5https://github.com/jthornber/device-mapper-test-suite}(hj hhhNhNubah}(h]h ]h"]h$]h&]refurij uh1j hj ubah}(h]h ]h"]h$]h&]uh1hhhhMIhj} hhubj/)}(hXPdmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \ /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0' dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \ /dev/mapper/ssd /dev/mapper/origin 1024 1 writeback \ mq 4 sequential_threshold 1024 random_threshold 8'h]hXPdmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \ /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0' dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \ /dev/mapper/ssd /dev/mapper/origin 1024 1 writeback \ mq 4 sequential_threshold 1024 random_threshold 8'}hj sbah}(h]h ]h"]h$]h&]j>j?uh1j.hhhMMhj} hhubeh}(h]examplesah ]h"]examplesah$]h&]uh1hhhhhhhhMEubeh}(h]cacheah ]h"]cacheah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksjpfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j j jjjjjjjxjujjj j jAj>jvjsjjjjjjjz jw jjj j jr jo j j u nametypes}(j jjjjxjj jAjvjjjjz jj jr j uh}(j hjhjjjjjujjj{j jj>jjsjDjjyjjjjjw jjjj jjo j j j} u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.