writecache.rst

  1=================
  2Writecache target
  3=================
  4
  5The writecache target caches writes on persistent memory or on SSD. It
  6doesn't cache reads because reads are supposed to be cached in page cache
  7in normal RAM.
  8
  9When the device is constructed, the first sector should be zeroed or the
 10first sector should contain valid superblock from previous invocation.
 11
 12Constructor parameters:
 13
 141. type of the cache device - "p" or "s"
 15	- p - persistent memory
 16	- s - SSD
 172. the underlying device that will be cached
 183. the cache device
 194. block size (4096 is recommended; the maximum block size is the page
 20   size)
 215. 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
 77Status:
 78
 791. error indicator - 0 if there was no error, otherwise error number
 802. the number of blocks
 813. the number of free blocks
 824. the number of blocks under writeback
 835. the number of read blocks
 846. the number of read blocks that hit the cache
 857. the number of write blocks
 868. the number of write blocks that hit uncommitted block
 879. the number of write blocks that hit committed block
 8810. the number of write blocks that bypass the cache
 8911. the number of write blocks that are allocated in the cache
 9012. the number of write requests that are blocked on the freelist
 9113. the number of flush requests
 9214. the number of discarded blocks
 93
 94Messages:
 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