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