1dm-dust 2======= 3 4This target emulates the behavior of bad sectors at arbitrary 5locations, and the ability to enable the emulation of the failures 6at an arbitrary time. 7 8This target behaves similarly to a linear target. At a given time, 9the user can send a message to the target to start failing read 10requests on specific blocks (to emulate the behavior of a hard disk 11drive with bad sectors). 12 13When the failure behavior is enabled (i.e.: when the output of 14"dmsetup status" displays "fail_read_on_bad_block"), reads of blocks 15in the "bad block list" will fail with EIO ("Input/output error"). 16 17Writes of blocks in the "bad block list will result in the following: 18 191. Remove the block from the "bad block list". 202. Successfully complete the write. 21 22This emulates the "remapped sector" behavior of a drive with bad 23sectors. 24 25Normally, a drive that is encountering bad sectors will most likely 26encounter more bad sectors, at an unknown time or location. 27With dm-dust, the user can use the "addbadblock" and "removebadblock" 28messages to add arbitrary bad blocks at new locations, and the 29"enable" and "disable" messages to modulate the state of whether the 30configured "bad blocks" will be treated as bad, or bypassed. 31This allows the pre-writing of test data and metadata prior to 32simulating a "failure" event where bad sectors start to appear. 33 34Table parameters 35---------------- 36<device_path> <offset> <blksz> 37 38Mandatory parameters: 39 <device_path>: 40 Path to the block device. 41 42 <offset>: 43 Offset to data area from start of device_path 44 45 <blksz>: 46 Block size in bytes 47 48 (minimum 512, maximum 1073741824, must be a power of 2) 49 50Usage instructions 51------------------ 52 53First, find the size (in 512-byte sectors) of the device to be used:: 54 55 $ sudo blockdev --getsz /dev/vdb1 56 33552384 57 58Create the dm-dust device: 59(For a device with a block size of 512 bytes) 60 61:: 62 63 $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 512' 64 65(For a device with a block size of 4096 bytes) 66 67:: 68 69 $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096' 70 71Check the status of the read behavior ("bypass" indicates that all I/O 72will be passed through to the underlying device; "verbose" indicates that 73bad block additions, removals, and remaps will be verbosely logged):: 74 75 $ sudo dmsetup status dust1 76 0 33552384 dust 252:17 bypass verbose 77 78 $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct 79 128+0 records in 80 128+0 records out 81 82 $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct 83 128+0 records in 84 128+0 records out 85 86Adding and removing bad blocks 87------------------------------ 88 89At any time (i.e.: whether the device has the "bad block" emulation 90enabled or disabled), bad blocks may be added or removed from the 91device via the "addbadblock" and "removebadblock" messages:: 92 93 $ sudo dmsetup message dust1 0 addbadblock 60 94 kernel: device-mapper: dust: badblock added at block 60 95 96 $ sudo dmsetup message dust1 0 addbadblock 67 97 kernel: device-mapper: dust: badblock added at block 67 98 99 $ sudo dmsetup message dust1 0 addbadblock 72 100 kernel: device-mapper: dust: badblock added at block 72 101 102These bad blocks will be stored in the "bad block list". 103While the device is in "bypass" mode, reads and writes will succeed:: 104 105 $ sudo dmsetup status dust1 106 0 33552384 dust 252:17 bypass 107 108Enabling block read failures 109---------------------------- 110 111To enable the "fail read on bad block" behavior, send the "enable" message:: 112 113 $ sudo dmsetup message dust1 0 enable 114 kernel: device-mapper: dust: enabling read failures on bad sectors 115 116 $ sudo dmsetup status dust1 117 0 33552384 dust 252:17 fail_read_on_bad_block 118 119With the device in "fail read on bad block" mode, attempting to read a 120block will encounter an "Input/output error":: 121 122 $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct 123 dd: error reading '/dev/mapper/dust1': Input/output error 124 0+0 records in 125 0+0 records out 126 0 bytes copied, 0.00040651 s, 0.0 kB/s 127 128...and writing to the bad blocks will remove the blocks from the list, 129therefore emulating the "remap" behavior of hard disk drives:: 130 131 $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct 132 128+0 records in 133 128+0 records out 134 135 kernel: device-mapper: dust: block 60 removed from badblocklist by write 136 kernel: device-mapper: dust: block 67 removed from badblocklist by write 137 kernel: device-mapper: dust: block 72 removed from badblocklist by write 138 kernel: device-mapper: dust: block 87 removed from badblocklist by write 139 140Bad block add/remove error handling 141----------------------------------- 142 143Attempting to add a bad block that already exists in the list will 144result in an "Invalid argument" error, as well as a helpful message:: 145 146 $ sudo dmsetup message dust1 0 addbadblock 88 147 device-mapper: message ioctl on dust1 failed: Invalid argument 148 kernel: device-mapper: dust: block 88 already in badblocklist 149 150Attempting to remove a bad block that doesn't exist in the list will 151result in an "Invalid argument" error, as well as a helpful message:: 152 153 $ sudo dmsetup message dust1 0 removebadblock 87 154 device-mapper: message ioctl on dust1 failed: Invalid argument 155 kernel: device-mapper: dust: block 87 not found in badblocklist 156 157Counting the number of bad blocks in the bad block list 158------------------------------------------------------- 159 160To count the number of bad blocks configured in the device, run the 161following message command:: 162 163 $ sudo dmsetup message dust1 0 countbadblocks 164 165A message will print with the number of bad blocks currently 166configured on the device:: 167 168 countbadblocks: 895 badblock(s) found 169 170Querying for specific bad blocks 171-------------------------------- 172 173To find out if a specific block is in the bad block list, run the 174following message command:: 175 176 $ sudo dmsetup message dust1 0 queryblock 72 177 178The following message will print if the block is in the list:: 179 180 dust_query_block: block 72 found in badblocklist 181 182The following message will print if the block is not in the list:: 183 184 dust_query_block: block 72 not found in badblocklist 185 186The "queryblock" message command will work in both the "enabled" 187and "disabled" modes, allowing the verification of whether a block 188will be treated as "bad" without having to issue I/O to the device, 189or having to "enable" the bad block emulation. 190 191Clearing the bad block list 192--------------------------- 193 194To clear the bad block list (without needing to individually run 195a "removebadblock" message command for every block), run the 196following message command:: 197 198 $ sudo dmsetup message dust1 0 clearbadblocks 199 200After clearing the bad block list, the following message will appear:: 201 202 dust_clear_badblocks: badblocks cleared 203 204If there were no bad blocks to clear, the following message will 205appear:: 206 207 dust_clear_badblocks: no badblocks found 208 209Listing the bad block list 210-------------------------- 211 212To list all bad blocks in the bad block list (using an example device 213with blocks 1 and 2 in the bad block list), run the following message 214command:: 215 216 $ sudo dmsetup message dust1 0 listbadblocks 217 1 218 2 219 220If there are no bad blocks in the bad block list, the command will 221execute with no output:: 222 223 $ sudo dmsetup message dust1 0 listbadblocks 224 225Message commands list 226--------------------- 227 228Below is a list of the messages that can be sent to a dust device: 229 230Operations on blocks (requires a <blknum> argument):: 231 232 addbadblock <blknum> 233 queryblock <blknum> 234 removebadblock <blknum> 235 236...where <blknum> is a block number within range of the device 237(corresponding to the block size of the device.) 238 239Single argument message commands:: 240 241 countbadblocks 242 clearbadblocks 243 listbadblocks 244 disable 245 enable 246 quiet 247 248Device removal 249-------------- 250 251When finished, remove the device via the "dmsetup remove" command:: 252 253 $ sudo dmsetup remove dust1 254 255Quiet mode 256---------- 257 258On test runs with many bad blocks, it may be desirable to avoid 259excessive logging (from bad blocks added, removed, or "remapped"). 260This can be done by enabling "quiet mode" via the following message:: 261 262 $ sudo dmsetup message dust1 0 quiet 263 264This will suppress log messages from add / remove / removed by write 265operations. Log messages from "countbadblocks" or "queryblock" 266message commands will still print in quiet mode. 267 268The status of quiet mode can be seen by running "dmsetup status":: 269 270 $ sudo dmsetup status dust1 271 0 33552384 dust 252:17 fail_read_on_bad_block quiet 272 273To disable quiet mode, send the "quiet" message again:: 274 275 $ sudo dmsetup message dust1 0 quiet 276 277 $ sudo dmsetup status dust1 278 0 33552384 dust 252:17 fail_read_on_bad_block verbose 279 280(The presence of "verbose" indicates normal logging.) 281 282"Why not...?" 283------------- 284 285scsi_debug has a "medium error" mode that can fail reads on one 286specified sector (sector 0x1234, hardcoded in the source code), but 287it uses RAM for the persistent storage, which drastically decreases 288the potential device size. 289 290dm-flakey fails all I/O from all block locations at a specified time 291frequency, and not a given point in time. 292 293When a bad sector occurs on a hard disk drive, reads to that sector 294are failed by the device, usually resulting in an error code of EIO 295("I/O error") or ENODATA ("No data available"). However, a write to 296the sector may succeed, and result in the sector becoming readable 297after the device controller no longer experiences errors reading the 298sector (or after a reallocation of the sector). However, there may 299be bad sectors that occur on the device in the future, in a different, 300unpredictable location. 301 302This target seeks to provide a device that can exhibit the behavior 303of a bad sector at a known sector location, at a known time, based 304on a large storage device (at least tens of gigabytes, not occupying 305system memory). 306