diff options
Diffstat (limited to 'Documentation/admin-guide/device-mapper/writecache.rst')
| -rw-r--r-- | Documentation/admin-guide/device-mapper/writecache.rst | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/Documentation/admin-guide/device-mapper/writecache.rst b/Documentation/admin-guide/device-mapper/writecache.rst new file mode 100644 index 000000000000..d3d7690f5e8d --- /dev/null +++ b/Documentation/admin-guide/device-mapper/writecache.rst | |||
| @@ -0,0 +1,79 @@ | |||
| 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 | |||
| 16 | - p - persistent memory | ||
| 17 | - s - SSD | ||
| 18 | 2. the underlying device that will be cached | ||
| 19 | 3. the cache device | ||
| 20 | 4. block size (4096 is recommended; the maximum block size is the page | ||
| 21 | size) | ||
| 22 | 5. the number of optional parameters (the parameters with an argument | ||
| 23 | count as two) | ||
| 24 | |||
| 25 | start_sector n (default: 0) | ||
| 26 | offset from the start of cache device in 512-byte sectors | ||
| 27 | high_watermark n (default: 50) | ||
| 28 | start writeback when the number of used blocks reach this | ||
| 29 | watermark | ||
| 30 | low_watermark x (default: 45) | ||
| 31 | stop writeback when the number of used blocks drops below | ||
| 32 | this watermark | ||
| 33 | writeback_jobs n (default: unlimited) | ||
| 34 | limit the number of blocks that are in flight during | ||
| 35 | writeback. Setting this value reduces writeback | ||
| 36 | throughput, but it may improve latency of read requests | ||
| 37 | autocommit_blocks n (default: 64 for pmem, 65536 for ssd) | ||
| 38 | when the application writes this amount of blocks without | ||
| 39 | issuing the FLUSH request, the blocks are automatically | ||
| 40 | commited | ||
| 41 | autocommit_time ms (default: 1000) | ||
| 42 | autocommit time in milliseconds. The data is automatically | ||
| 43 | commited if this time passes and no FLUSH request is | ||
| 44 | received | ||
| 45 | fua (by default on) | ||
| 46 | applicable only to persistent memory - use the FUA flag | ||
| 47 | when writing data from persistent memory back to the | ||
| 48 | underlying device | ||
| 49 | nofua | ||
| 50 | applicable only to persistent memory - don't use the FUA | ||
| 51 | flag when writing back data and send the FLUSH request | ||
| 52 | afterwards | ||
| 53 | |||
| 54 | - some underlying devices perform better with fua, some | ||
| 55 | with nofua. The user should test it | ||
| 56 | |||
| 57 | Status: | ||
| 58 | 1. error indicator - 0 if there was no error, otherwise error number | ||
| 59 | 2. the number of blocks | ||
| 60 | 3. the number of free blocks | ||
| 61 | 4. the number of blocks under writeback | ||
| 62 | |||
| 63 | Messages: | ||
| 64 | flush | ||
| 65 | flush the cache device. The message returns successfully | ||
| 66 | if the cache device was flushed without an error | ||
| 67 | flush_on_suspend | ||
| 68 | flush the cache device on next suspend. Use this message | ||
| 69 | when you are going to remove the cache device. The proper | ||
| 70 | sequence for removing the cache device is: | ||
| 71 | |||
| 72 | 1. send the "flush_on_suspend" message | ||
| 73 | 2. load an inactive table with a linear target that maps | ||
| 74 | to the underlying device | ||
| 75 | 3. suspend the device | ||
| 76 | 4. ask for status and verify that there are no errors | ||
| 77 | 5. resume the device, so that it will use the linear | ||
| 78 | target | ||
| 79 | 6. the cache device is now inactive and it can be deleted | ||