1============= 2dm-log-writes 3============= 4 5This target takes 2 devices, one to pass all IO to normally, and one to log all 6of the write operations to. This is intended for file system developers wishing 7to verify the integrity of metadata or data as the file system is written to. 8There is a log_write_entry written for every WRITE request and the target is 9able to take arbitrary data from userspace to insert into the log. The data 10that is in the WRITE requests is copied into the log to make the replay happen 11exactly as it happened originally. 12 13Log Ordering 14============ 15 16We log things in order of completion once we are sure the write is no longer in 17cache. This means that normal WRITE requests are not actually logged until the 18next REQ_PREFLUSH request. This is to make it easier for userspace to replay 19the log in a way that correlates to what is on disk and not what is in cache, 20to make it easier to detect improper waiting/flushing. 21 22This works by attaching all WRITE requests to a list once the write completes. 23Once we see a REQ_PREFLUSH request we splice this list onto the request and once 24the FLUSH request completes we log all of the WRITEs and then the FLUSH. Only 25completed WRITEs, at the time the REQ_PREFLUSH is issued, are added in order to 26simulate the worst case scenario with regard to power failures. Consider the 27following example (W means write, C means complete): 28 29 W1,W2,W3,C3,C2,Wflush,C1,Cflush 30 31The log would show the following: 32 33 W3,W2,flush,W1.... 34 35Again this is to simulate what is actually on disk, this allows us to detect 36cases where a power failure at a particular point in time would create an 37inconsistent file system. 38 39Any REQ_FUA requests bypass this flushing mechanism and are logged as soon as 40they complete as those requests will obviously bypass the device cache. 41 42Any REQ_OP_DISCARD requests are treated like WRITE requests. Otherwise we would 43have all the DISCARD requests, and then the WRITE requests and then the FLUSH 44request. Consider the following example: 45 46 WRITE block 1, DISCARD block 1, FLUSH 47 48If we logged DISCARD when it completed, the replay would look like this: 49 50 DISCARD 1, WRITE 1, FLUSH 51 52which isn't quite what happened and wouldn't be caught during the log replay. 53 54Target interface 55================ 56 57i) Constructor 58 59 log-writes <dev_path> <log_dev_path> 60 61 ============= ============================================== 62 dev_path Device that all of the IO will go to normally. 63 log_dev_path Device where the log entries are written to. 64 ============= ============================================== 65 66ii) Status 67 68 <#logged entries> <highest allocated sector> 69 70 =========================== ======================== 71 #logged entries Number of logged entries 72 highest allocated sector Highest allocated sector 73 =========================== ======================== 74 75iii) Messages 76 77 mark <description> 78 79 You can use a dmsetup message to set an arbitrary mark in a log. 80 For example say you want to fsck a file system after every 81 write, but first you need to replay up to the mkfs to make sure 82 we're fsck'ing something reasonable, you would do something like 83 this:: 84 85 mkfs.btrfs -f /dev/mapper/log 86 dmsetup message log 0 mark mkfs 87 <run test> 88 89 This would allow you to replay the log up to the mkfs mark and 90 then replay from that point on doing the fsck check in the 91 interval that you want. 92 93 Every log has a mark at the end labeled "dm-log-writes-end". 94 95Userspace component 96=================== 97 98There is a userspace tool that will replay the log for you in various ways. 99It can be found here: https://github.com/josefbacik/log-writes 100 101Example usage 102============= 103 104Say you want to test fsync on your file system. You would do something like 105this:: 106 107 TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc" 108 dmsetup create log --table "$TABLE" 109 mkfs.btrfs -f /dev/mapper/log 110 dmsetup message log 0 mark mkfs 111 112 mount /dev/mapper/log /mnt/btrfs-test 113 <some test that does fsync at the end> 114 dmsetup message log 0 mark fsync 115 md5sum /mnt/btrfs-test/foo 116 umount /mnt/btrfs-test 117 118 dmsetup remove log 119 replay-log --log /dev/sdc --replay /dev/sdb --end-mark fsync 120 mount /dev/sdb /mnt/btrfs-test 121 md5sum /mnt/btrfs-test/foo 122 <verify md5sum's are correct> 123 124 Another option is to do a complicated file system operation and verify the file 125 system is consistent during the entire operation. You could do this with: 126 127 TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc" 128 dmsetup create log --table "$TABLE" 129 mkfs.btrfs -f /dev/mapper/log 130 dmsetup message log 0 mark mkfs 131 132 mount /dev/mapper/log /mnt/btrfs-test 133 <fsstress to dirty the fs> 134 btrfs filesystem balance /mnt/btrfs-test 135 umount /mnt/btrfs-test 136 dmsetup remove log 137 138 replay-log --log /dev/sdc --replay /dev/sdb --end-mark mkfs 139 btrfsck /dev/sdb 140 replay-log --log /dev/sdc --replay /dev/sdb --start-mark mkfs \ 141 --fsck "btrfsck /dev/sdb" --check fua 142 143And that will replay the log until it sees a FUA request, run the fsck command 144and if the fsck passes it will replay to the next FUA, until it is completed or 145the fsck command exists abnormally. 146