| 1 | =================
|
| 2 | Writecache target
|
| 3 | =================
|
| 4 |
|
| 5 | The writecache target caches writes on persistent memory or on SSD. It
|
| 6 | doesn't cache reads because reads are supposed to be cached in page cache
|
| 7 | in normal RAM.
|
| 8 |
|
| 9 | When the device is constructed, the first sector should be zeroed or the
|
| 10 | first sector should contain valid superblock from previous invocation.
|
| 11 |
|
| 12 | Constructor parameters:
|
| 13 |
|
| 14 | 1. type of the cache device - "p" or "s"
|
| 15 | - p - persistent memory
|
| 16 | - s - SSD
|
| 17 | 2. the underlying device that will be cached
|
| 18 | 3. the cache device
|
| 19 | 4. block size (4096 is recommended; the maximum block size is the page
|
| 20 | size)
|
| 21 | 5. the number of optional parameters (the parameters with an argument
|
| 22 | count as two)
|
| 23 |
|
| 24 | start_sector n (default: 0)
|
| 25 | offset from the start of cache device in 512-byte sectors
|
| 26 | high_watermark n (default: 50)
|
| 27 | start writeback when the number of used blocks reach this
|
| 28 | watermark
|
| 29 | low_watermark x (default: 45)
|
| 30 | stop writeback when the number of used blocks drops below
|
| 31 | this watermark
|
| 32 | writeback_jobs n (default: unlimited)
|
| 33 | limit the number of blocks that are in flight during
|
| 34 | writeback. Setting this value reduces writeback
|
| 35 | throughput, but it may improve latency of read requests
|
| 36 | autocommit_blocks n (default: 64 for pmem, 65536 for ssd)
|
| 37 | when the application writes this amount of blocks without
|
| 38 | issuing the FLUSH request, the blocks are automatically
|
| 39 | committed
|
| 40 | autocommit_time ms (default: 1000)
|
| 41 | autocommit time in milliseconds. The data is automatically
|
| 42 | committed if this time passes and no FLUSH request is
|
| 43 | received
|
| 44 | fua (by default on)
|
| 45 | applicable only to persistent memory - use the FUA flag
|
| 46 | when writing data from persistent memory back to the
|
| 47 | underlying device
|
| 48 | nofua
|
| 49 | applicable only to persistent memory - don't use the FUA
|
| 50 | flag when writing back data and send the FLUSH request
|
| 51 | afterwards
|
| 52 |
|
| 53 | - some underlying devices perform better with fua, some
|
| 54 | with nofua. The user should test it
|
| 55 | cleaner
|
| 56 | when this option is activated (either in the constructor
|
| 57 | arguments or by a message), the cache will not promote
|
| 58 | new writes (however, writes to already cached blocks are
|
| 59 | promoted, to avoid data corruption due to misordered
|
| 60 | writes) and it will gradually writeback any cached
|
| 61 | data. The userspace can then monitor the cleaning
|
| 62 | process with "dmsetup status". When the number of cached
|
| 63 | blocks drops to zero, userspace can unload the
|
| 64 | dm-writecache target and replace it with dm-linear or
|
| 65 | other targets.
|
| 66 | max_age n
|
| 67 | specifies the maximum age of a block in milliseconds. If
|
| 68 | a block is stored in the cache for too long, it will be
|
| 69 | written to the underlying device and cleaned up.
|
| 70 | metadata_only
|
| 71 | only metadata is promoted to the cache. This option
|
| 72 | improves performance for heavier REQ_META workloads.
|
| 73 | pause_writeback n (default: 3000)
|
| 74 | pause writeback if there was some write I/O redirected to
|
| 75 | the origin volume in the last n milliseconds
|
| 76 |
|
| 77 | Status:
|
| 78 |
|
| 79 | 1. error indicator - 0 if there was no error, otherwise error number
|
| 80 | 2. the number of blocks
|
| 81 | 3. the number of free blocks
|
| 82 | 4. the number of blocks under writeback
|
| 83 | 5. the number of read blocks
|
| 84 | 6. the number of read blocks that hit the cache
|
| 85 | 7. the number of write blocks
|
| 86 | 8. the number of write blocks that hit uncommitted block
|
| 87 | 9. the number of write blocks that hit committed block
|
| 88 | 10. the number of write blocks that bypass the cache
|
| 89 | 11. the number of write blocks that are allocated in the cache
|
| 90 | 12. the number of write requests that are blocked on the freelist
|
| 91 | 13. the number of flush requests
|
| 92 | 14. the number of discarded blocks
|
| 93 |
|
| 94 | Messages:
|
| 95 | flush
|
| 96 | Flush the cache device. The message returns successfully
|
| 97 | if the cache device was flushed without an error
|
| 98 | flush_on_suspend
|
| 99 | Flush the cache device on next suspend. Use this message
|
| 100 | when you are going to remove the cache device. The proper
|
| 101 | sequence for removing the cache device is:
|
| 102 |
|
| 103 | 1. send the "flush_on_suspend" message
|
| 104 | 2. load an inactive table with a linear target that maps
|
| 105 | to the underlying device
|
| 106 | 3. suspend the device
|
| 107 | 4. ask for status and verify that there are no errors
|
| 108 | 5. resume the device, so that it will use the linear
|
| 109 | target
|
| 110 | 6. the cache device is now inactive and it can be deleted
|
| 111 | cleaner
|
| 112 | See above "cleaner" constructor documentation.
|
| 113 | clear_stats
|
| 114 | Clear the statistics that are reported on the status line
|