| b.liu | e958203 | 2025-04-17 19:18:16 +0800 | [diff] [blame^] | 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 |