0001 =================
0002 Writecache target
0003 =================
0004
0005 The writecache target caches writes on persistent memory or on SSD. It
0006 doesn't cache reads because reads are supposed to be cached in page cache
0007 in normal RAM.
0008
0009 When the device is constructed, the first sector should be zeroed or the
0010 first sector should contain valid superblock from previous invocation.
0011
0012 Constructor parameters:
0013
0014 1. type of the cache device - "p" or "s"
0015 - p - persistent memory
0016 - s - SSD
0017 2. the underlying device that will be cached
0018 3. the cache device
0019 4. block size (4096 is recommended; the maximum block size is the page
0020 size)
0021 5. the number of optional parameters (the parameters with an argument
0022 count as two)
0023
0024 start_sector n (default: 0)
0025 offset from the start of cache device in 512-byte sectors
0026 high_watermark n (default: 50)
0027 start writeback when the number of used blocks reach this
0028 watermark
0029 low_watermark x (default: 45)
0030 stop writeback when the number of used blocks drops below
0031 this watermark
0032 writeback_jobs n (default: unlimited)
0033 limit the number of blocks that are in flight during
0034 writeback. Setting this value reduces writeback
0035 throughput, but it may improve latency of read requests
0036 autocommit_blocks n (default: 64 for pmem, 65536 for ssd)
0037 when the application writes this amount of blocks without
0038 issuing the FLUSH request, the blocks are automatically
0039 committed
0040 autocommit_time ms (default: 1000)
0041 autocommit time in milliseconds. The data is automatically
0042 committed if this time passes and no FLUSH request is
0043 received
0044 fua (by default on)
0045 applicable only to persistent memory - use the FUA flag
0046 when writing data from persistent memory back to the
0047 underlying device
0048 nofua
0049 applicable only to persistent memory - don't use the FUA
0050 flag when writing back data and send the FLUSH request
0051 afterwards
0052
0053 - some underlying devices perform better with fua, some
0054 with nofua. The user should test it
0055 cleaner
0056 when this option is activated (either in the constructor
0057 arguments or by a message), the cache will not promote
0058 new writes (however, writes to already cached blocks are
0059 promoted, to avoid data corruption due to misordered
0060 writes) and it will gradually writeback any cached
0061 data. The userspace can then monitor the cleaning
0062 process with "dmsetup status". When the number of cached
0063 blocks drops to zero, userspace can unload the
0064 dm-writecache target and replace it with dm-linear or
0065 other targets.
0066 max_age n
0067 specifies the maximum age of a block in milliseconds. If
0068 a block is stored in the cache for too long, it will be
0069 written to the underlying device and cleaned up.
0070 metadata_only
0071 only metadata is promoted to the cache. This option
0072 improves performance for heavier REQ_META workloads.
0073 pause_writeback n (default: 3000)
0074 pause writeback if there was some write I/O redirected to
0075 the origin volume in the last n milliseconds
0076
0077 Status:
0078
0079 1. error indicator - 0 if there was no error, otherwise error number
0080 2. the number of blocks
0081 3. the number of free blocks
0082 4. the number of blocks under writeback
0083 5. the number of read blocks
0084 6. the number of read blocks that hit the cache
0085 7. the number of write blocks
0086 8. the number of write blocks that hit uncommitted block
0087 9. the number of write blocks that hit committed block
0088 10. the number of write blocks that bypass the cache
0089 11. the number of write blocks that are allocated in the cache
0090 12. the number of write requests that are blocked on the freelist
0091 13. the number of flush requests
0092 14. the number of discarded blocks
0093
0094 Messages:
0095 flush
0096 Flush the cache device. The message returns successfully
0097 if the cache device was flushed without an error
0098 flush_on_suspend
0099 Flush the cache device on next suspend. Use this message
0100 when you are going to remove the cache device. The proper
0101 sequence for removing the cache device is:
0102
0103 1. send the "flush_on_suspend" message
0104 2. load an inactive table with a linear target that maps
0105 to the underlying device
0106 3. suspend the device
0107 4. ask for status and verify that there are no errors
0108 5. resume the device, so that it will use the linear
0109 target
0110 6. the cache device is now inactive and it can be deleted
0111 cleaner
0112 See above "cleaner" constructor documentation.
0113 clear_stats
0114 Clear the statistics that are reported on the status line
