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