306 lines · plain
1dm-dust2=======3 4This target emulates the behavior of bad sectors at arbitrary5locations, and the ability to enable the emulation of the failures6at 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 read10requests on specific blocks (to emulate the behavior of a hard disk11drive with bad sectors).12 13When the failure behavior is enabled (i.e.: when the output of14"dmsetup status" displays "fail_read_on_bad_block"), reads of blocks15in 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 bad23sectors.24 25Normally, a drive that is encountering bad sectors will most likely26encounter 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 the29"enable" and "disable" messages to modulate the state of whether the30configured "bad blocks" will be treated as bad, or bypassed.31This allows the pre-writing of test data and metadata prior to32simulating a "failure" event where bad sectors start to appear.33 34Table parameters35----------------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_path44 45 <blksz>:46 Block size in bytes47 48 (minimum 512, maximum 1073741824, must be a power of 2)49 50Usage instructions51------------------52 53First, find the size (in 512-byte sectors) of the device to be used::54 55 $ sudo blockdev --getsz /dev/vdb156 3355238457 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/O72will be passed through to the underlying device; "verbose" indicates that73bad block additions, removals, and remaps will be verbosely logged)::74 75 $ sudo dmsetup status dust176 0 33552384 dust 252:17 bypass verbose77 78 $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct79 128+0 records in80 128+0 records out81 82 $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct83 128+0 records in84 128+0 records out85 86Adding and removing bad blocks87------------------------------88 89At any time (i.e.: whether the device has the "bad block" emulation90enabled or disabled), bad blocks may be added or removed from the91device via the "addbadblock" and "removebadblock" messages::92 93 $ sudo dmsetup message dust1 0 addbadblock 6094 kernel: device-mapper: dust: badblock added at block 6095 96 $ sudo dmsetup message dust1 0 addbadblock 6797 kernel: device-mapper: dust: badblock added at block 6798 99 $ sudo dmsetup message dust1 0 addbadblock 72100 kernel: device-mapper: dust: badblock added at block 72101 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 dust1106 0 33552384 dust 252:17 bypass107 108Enabling block read failures109----------------------------110 111To enable the "fail read on bad block" behavior, send the "enable" message::112 113 $ sudo dmsetup message dust1 0 enable114 kernel: device-mapper: dust: enabling read failures on bad sectors115 116 $ sudo dmsetup status dust1117 0 33552384 dust 252:17 fail_read_on_bad_block118 119With the device in "fail read on bad block" mode, attempting to read a120block will encounter an "Input/output error"::121 122 $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct123 dd: error reading '/dev/mapper/dust1': Input/output error124 0+0 records in125 0+0 records out126 0 bytes copied, 0.00040651 s, 0.0 kB/s127 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=direct132 128+0 records in133 128+0 records out134 135 kernel: device-mapper: dust: block 60 removed from badblocklist by write136 kernel: device-mapper: dust: block 67 removed from badblocklist by write137 kernel: device-mapper: dust: block 72 removed from badblocklist by write138 kernel: device-mapper: dust: block 87 removed from badblocklist by write139 140Bad block add/remove error handling141-----------------------------------142 143Attempting to add a bad block that already exists in the list will144result in an "Invalid argument" error, as well as a helpful message::145 146 $ sudo dmsetup message dust1 0 addbadblock 88147 device-mapper: message ioctl on dust1 failed: Invalid argument148 kernel: device-mapper: dust: block 88 already in badblocklist149 150Attempting to remove a bad block that doesn't exist in the list will151result in an "Invalid argument" error, as well as a helpful message::152 153 $ sudo dmsetup message dust1 0 removebadblock 87154 device-mapper: message ioctl on dust1 failed: Invalid argument155 kernel: device-mapper: dust: block 87 not found in badblocklist156 157Counting the number of bad blocks in the bad block list158-------------------------------------------------------159 160To count the number of bad blocks configured in the device, run the161following message command::162 163 $ sudo dmsetup message dust1 0 countbadblocks164 165A message will print with the number of bad blocks currently166configured on the device::167 168 countbadblocks: 895 badblock(s) found169 170Querying for specific bad blocks171--------------------------------172 173To find out if a specific block is in the bad block list, run the174following message command::175 176 $ sudo dmsetup message dust1 0 queryblock 72177 178The following message will print if the block is in the list::179 180 dust_query_block: block 72 found in badblocklist181 182The following message will print if the block is not in the list::183 184 dust_query_block: block 72 not found in badblocklist185 186The "queryblock" message command will work in both the "enabled"187and "disabled" modes, allowing the verification of whether a block188will 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 list192---------------------------193 194To clear the bad block list (without needing to individually run195a "removebadblock" message command for every block), run the196following message command::197 198 $ sudo dmsetup message dust1 0 clearbadblocks199 200After clearing the bad block list, the following message will appear::201 202 dust_clear_badblocks: badblocks cleared203 204If there were no bad blocks to clear, the following message will205appear::206 207 dust_clear_badblocks: no badblocks found208 209Listing the bad block list210--------------------------211 212To list all bad blocks in the bad block list (using an example device213with blocks 1 and 2 in the bad block list), run the following message214command::215 216 $ sudo dmsetup message dust1 0 listbadblocks217 1218 2219 220If there are no bad blocks in the bad block list, the command will221execute with no output::222 223 $ sudo dmsetup message dust1 0 listbadblocks224 225Message commands list226---------------------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 device237(corresponding to the block size of the device.)238 239Single argument message commands::240 241 countbadblocks242 clearbadblocks243 listbadblocks244 disable245 enable246 quiet247 248Device removal249--------------250 251When finished, remove the device via the "dmsetup remove" command::252 253 $ sudo dmsetup remove dust1254 255Quiet mode256----------257 258On test runs with many bad blocks, it may be desirable to avoid259excessive 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 quiet263 264This will suppress log messages from add / remove / removed by write265operations. 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 dust1271 0 33552384 dust 252:17 fail_read_on_bad_block quiet272 273To disable quiet mode, send the "quiet" message again::274 275 $ sudo dmsetup message dust1 0 quiet276 277 $ sudo dmsetup status dust1278 0 33552384 dust 252:17 fail_read_on_bad_block verbose279 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 one286specified sector (sector 0x1234, hardcoded in the source code), but287it uses RAM for the persistent storage, which drastically decreases288the potential device size.289 290dm-flakey fails all I/O from all block locations at a specified time291frequency, and not a given point in time.292 293When a bad sector occurs on a hard disk drive, reads to that sector294are failed by the device, usually resulting in an error code of EIO295("I/O error") or ENODATA ("No data available"). However, a write to296the sector may succeed, and result in the sector becoming readable297after the device controller no longer experiences errors reading the298sector (or after a reallocation of the sector). However, there may299be 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 behavior303of a bad sector at a known sector location, at a known time, based304on a large storage device (at least tens of gigabytes, not occupying305system memory).306