diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2013-11-13 22:35:48 -0500 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2013-11-13 22:35:48 -0500 |
| commit | 7f2dc5c4bcbff035b0d03f7aa78a182664b21e47 (patch) | |
| tree | f4a5ff92305fbf70f1cba3a1ced0f492b27aab74 /Documentation | |
| parent | 82cb6acea4d10fa4080612c58deb63993f558e5a (diff) | |
| parent | 7b6b2bc98c0303b7f043ad5b35906f833e56308d (diff) | |
Merge tag 'dm-3.13-changes' of git://git.kernel.org/pub/scm/linux/kernel/git/device-mapper/linux-dm
Pull device mapper changes from Mike Snitzer:
"A set of device-mapper changes for 3.13.
Improve reliability of buffer allocations for dm messages with a small
number of arguments, a couple path group initialization fixes for dm
multipath, a fix for resizing a dm array, various fixes and
optimizations for dm cache, a fix for device mapper's Kconfig menu
indentation.
Features added include:
- dm crypt support for activating legacy CBC TrueCrypt containers
(useful for forensics of these old TCRYPT containers)
- reduced dm-cache memory requirements for each block in the cache
- basic support for shrinking a dm-cache's cache (fast) device
- most notably, dm-cache support for managing cache coherency when
deploying dm-cache with sophisticated origin volumes (that support
hardware snapshots and/or clustering): these changes come in the
form of a new passthrough operation mode and a cache block
invalidation interface"
* tag 'dm-3.13-changes' of git://git.kernel.org/pub/scm/linux/kernel/git/device-mapper/linux-dm: (32 commits)
dm cache: resolve small nits and improve Documentation
dm cache: add cache block invalidation support
dm cache: add remove_cblock method to policy interface
dm cache policy mq: reduce memory requirements
dm cache metadata: check the metadata version when reading the superblock
dm cache: add passthrough mode
dm cache: cache shrinking support
dm cache: promotion optimisation for writes
dm cache: be much more aggressive about promoting writes to discarded blocks
dm cache policy mq: implement writeback_work() and mq_{set,clear}_dirty()
dm cache: optimize commit_if_needed
dm space map disk: optimise sm_disk_dec_block
MAINTAINERS: add reference to device-mapper's linux-dm.git tree
dm: fix Kconfig menu indentation
dm: allow remove to be deferred
dm table: print error on preresume failure
dm crypt: add TCW IV mode for old CBC TCRYPT containers
dm crypt: properly handle extra key string in initialization
dm cache: log error message if dm_kcopyd_copy() fails
dm cache: use cell_defer() boolean argument consistently
...
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/device-mapper/cache-policies.txt | 6 | ||||
| -rw-r--r-- | Documentation/device-mapper/cache.txt | 57 | ||||
| -rw-r--r-- | Documentation/device-mapper/dm-crypt.txt | 11 |
3 files changed, 64 insertions, 10 deletions
diff --git a/Documentation/device-mapper/cache-policies.txt b/Documentation/device-mapper/cache-policies.txt index d7c440b444cc..df52a849957f 100644 --- a/Documentation/device-mapper/cache-policies.txt +++ b/Documentation/device-mapper/cache-policies.txt | |||
| @@ -30,8 +30,10 @@ multiqueue | |||
| 30 | 30 | ||
| 31 | This policy is the default. | 31 | This policy is the default. |
| 32 | 32 | ||
| 33 | The multiqueue policy has two sets of 16 queues: one set for entries | 33 | The multiqueue policy has three sets of 16 queues: one set for entries |
| 34 | waiting for the cache and another one for those in the cache. | 34 | waiting for the cache and another two for those in the cache (a set for |
| 35 | clean entries and a set for dirty entries). | ||
| 36 | |||
| 35 | Cache entries in the queues are aged based on logical time. Entry into | 37 | Cache entries in the queues are aged based on logical time. Entry into |
| 36 | the cache is based on variable thresholds and queue selection is based | 38 | the cache is based on variable thresholds and queue selection is based |
| 37 | on hit count on entry. The policy aims to take different cache miss | 39 | on hit count on entry. The policy aims to take different cache miss |
diff --git a/Documentation/device-mapper/cache.txt b/Documentation/device-mapper/cache.txt index 33d45ee0b737..274752f8bdf9 100644 --- a/Documentation/device-mapper/cache.txt +++ b/Documentation/device-mapper/cache.txt | |||
| @@ -68,10 +68,11 @@ So large block sizes are bad because they waste cache space. And small | |||
| 68 | block sizes are bad because they increase the amount of metadata (both | 68 | block sizes are bad because they increase the amount of metadata (both |
| 69 | in core and on disk). | 69 | in core and on disk). |
| 70 | 70 | ||
| 71 | Writeback/writethrough | 71 | Cache operating modes |
| 72 | ---------------------- | 72 | --------------------- |
| 73 | 73 | ||
| 74 | The cache has two modes, writeback and writethrough. | 74 | The cache has three operating modes: writeback, writethrough and |
| 75 | passthrough. | ||
| 75 | 76 | ||
| 76 | If writeback, the default, is selected then a write to a block that is | 77 | If writeback, the default, is selected then a write to a block that is |
| 77 | cached will go only to the cache and the block will be marked dirty in | 78 | cached will go only to the cache and the block will be marked dirty in |
| @@ -81,8 +82,31 @@ If writethrough is selected then a write to a cached block will not | |||
| 81 | complete until it has hit both the origin and cache devices. Clean | 82 | complete until it has hit both the origin and cache devices. Clean |
| 82 | blocks should remain clean. | 83 | blocks should remain clean. |
| 83 | 84 | ||
| 85 | If passthrough is selected, useful when the cache contents are not known | ||
| 86 | to be coherent with the origin device, then all reads are served from | ||
| 87 | the origin device (all reads miss the cache) and all writes are | ||
| 88 | forwarded to the origin device; additionally, write hits cause cache | ||
| 89 | block invalidates. To enable passthrough mode the cache must be clean. | ||
| 90 | Passthrough mode allows a cache device to be activated without having to | ||
| 91 | worry about coherency. Coherency that exists is maintained, although | ||
| 92 | the cache will gradually cool as writes take place. If the coherency of | ||
| 93 | the cache can later be verified, or established through use of the | ||
| 94 | "invalidate_cblocks" message, the cache device can be transitioned to | ||
| 95 | writethrough or writeback mode while still warm. Otherwise, the cache | ||
| 96 | contents can be discarded prior to transitioning to the desired | ||
| 97 | operating mode. | ||
| 98 | |||
| 84 | A simple cleaner policy is provided, which will clean (write back) all | 99 | A simple cleaner policy is provided, which will clean (write back) all |
| 85 | dirty blocks in a cache. Useful for decommissioning a cache. | 100 | dirty blocks in a cache. Useful for decommissioning a cache or when |
| 101 | shrinking a cache. Shrinking the cache's fast device requires all cache | ||
| 102 | blocks, in the area of the cache being removed, to be clean. If the | ||
| 103 | area being removed from the cache still contains dirty blocks the resize | ||
| 104 | will fail. Care must be taken to never reduce the volume used for the | ||
| 105 | cache's fast device until the cache is clean. This is of particular | ||
| 106 | importance if writeback mode is used. Writethrough and passthrough | ||
| 107 | modes already maintain a clean cache. Future support to partially clean | ||
| 108 | the cache, above a specified threshold, will allow for keeping the cache | ||
| 109 | warm and in writeback mode during resize. | ||
| 86 | 110 | ||
| 87 | Migration throttling | 111 | Migration throttling |
| 88 | -------------------- | 112 | -------------------- |
| @@ -161,7 +185,7 @@ Constructor | |||
| 161 | block size : cache unit size in sectors | 185 | block size : cache unit size in sectors |
| 162 | 186 | ||
| 163 | #feature args : number of feature arguments passed | 187 | #feature args : number of feature arguments passed |
| 164 | feature args : writethrough. (The default is writeback.) | 188 | feature args : writethrough or passthrough (The default is writeback.) |
| 165 | 189 | ||
| 166 | policy : the replacement policy to use | 190 | policy : the replacement policy to use |
| 167 | #policy args : an even number of arguments corresponding to | 191 | #policy args : an even number of arguments corresponding to |
| @@ -177,6 +201,13 @@ Optional feature arguments are: | |||
| 177 | back cache block contents later for performance reasons, | 201 | back cache block contents later for performance reasons, |
| 178 | so they may differ from the corresponding origin blocks. | 202 | so they may differ from the corresponding origin blocks. |
| 179 | 203 | ||
| 204 | passthrough : a degraded mode useful for various cache coherency | ||
| 205 | situations (e.g., rolling back snapshots of | ||
| 206 | underlying storage). Reads and writes always go to | ||
| 207 | the origin. If a write goes to a cached origin | ||
| 208 | block, then the cache block is invalidated. | ||
| 209 | To enable passthrough mode the cache must be clean. | ||
| 210 | |||
| 180 | A policy called 'default' is always registered. This is an alias for | 211 | A policy called 'default' is always registered. This is an alias for |
| 181 | the policy we currently think is giving best all round performance. | 212 | the policy we currently think is giving best all round performance. |
| 182 | 213 | ||
| @@ -231,12 +262,26 @@ The message format is: | |||
| 231 | E.g. | 262 | E.g. |
| 232 | dmsetup message my_cache 0 sequential_threshold 1024 | 263 | dmsetup message my_cache 0 sequential_threshold 1024 |
| 233 | 264 | ||
| 265 | |||
| 266 | Invalidation is removing an entry from the cache without writing it | ||
| 267 | back. Cache blocks can be invalidated via the invalidate_cblocks | ||
| 268 | message, which takes an arbitrary number of cblock ranges. Each cblock | ||
| 269 | must be expressed as a decimal value, in the future a variant message | ||
| 270 | that takes cblock ranges expressed in hexidecimal may be needed to | ||
| 271 | better support efficient invalidation of larger caches. The cache must | ||
| 272 | be in passthrough mode when invalidate_cblocks is used. | ||
| 273 | |||
| 274 | invalidate_cblocks [<cblock>|<cblock begin>-<cblock end>]* | ||
| 275 | |||
| 276 | E.g. | ||
| 277 | dmsetup message my_cache 0 invalidate_cblocks 2345 3456-4567 5678-6789 | ||
| 278 | |||
| 234 | Examples | 279 | Examples |
| 235 | ======== | 280 | ======== |
| 236 | 281 | ||
| 237 | The test suite can be found here: | 282 | The test suite can be found here: |
| 238 | 283 | ||
| 239 | https://github.com/jthornber/thinp-test-suite | 284 | https://github.com/jthornber/device-mapper-test-suite |
| 240 | 285 | ||
| 241 | dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \ | 286 | dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \ |
| 242 | /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0' | 287 | /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0' |
diff --git a/Documentation/device-mapper/dm-crypt.txt b/Documentation/device-mapper/dm-crypt.txt index 2c656ae43ba7..c81839b52c4d 100644 --- a/Documentation/device-mapper/dm-crypt.txt +++ b/Documentation/device-mapper/dm-crypt.txt | |||
| @@ -4,12 +4,15 @@ dm-crypt | |||
| 4 | Device-Mapper's "crypt" target provides transparent encryption of block devices | 4 | Device-Mapper's "crypt" target provides transparent encryption of block devices |
| 5 | using the kernel crypto API. | 5 | using the kernel crypto API. |
| 6 | 6 | ||
| 7 | For a more detailed description of supported parameters see: | ||
| 8 | http://code.google.com/p/cryptsetup/wiki/DMCrypt | ||
| 9 | |||
| 7 | Parameters: <cipher> <key> <iv_offset> <device path> \ | 10 | Parameters: <cipher> <key> <iv_offset> <device path> \ |
| 8 | <offset> [<#opt_params> <opt_params>] | 11 | <offset> [<#opt_params> <opt_params>] |
| 9 | 12 | ||
| 10 | <cipher> | 13 | <cipher> |
| 11 | Encryption cipher and an optional IV generation mode. | 14 | Encryption cipher and an optional IV generation mode. |
| 12 | (In format cipher[:keycount]-chainmode-ivopts:ivmode). | 15 | (In format cipher[:keycount]-chainmode-ivmode[:ivopts]). |
| 13 | Examples: | 16 | Examples: |
| 14 | des | 17 | des |
| 15 | aes-cbc-essiv:sha256 | 18 | aes-cbc-essiv:sha256 |
| @@ -19,7 +22,11 @@ Parameters: <cipher> <key> <iv_offset> <device path> \ | |||
| 19 | 22 | ||
| 20 | <key> | 23 | <key> |
| 21 | Key used for encryption. It is encoded as a hexadecimal number. | 24 | Key used for encryption. It is encoded as a hexadecimal number. |
| 22 | You can only use key sizes that are valid for the selected cipher. | 25 | You can only use key sizes that are valid for the selected cipher |
| 26 | in combination with the selected iv mode. | ||
| 27 | Note that for some iv modes the key string can contain additional | ||
| 28 | keys (for example IV seed) so the key contains more parts concatenated | ||
| 29 | into a single string. | ||
| 23 | 30 | ||
| 24 | <keycount> | 31 | <keycount> |
| 25 | Multi-key compatibility mode. You can define <keycount> keys and | 32 | Multi-key compatibility mode. You can define <keycount> keys and |