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; "verbose" indicates that
73 bad block additions, removals, and remaps will 73 bad block additions, removals, and remaps will be verbosely logged)::
74 74
75 $ sudo dmsetup status dust1 75 $ sudo dmsetup status dust1
76 0 33552384 dust 252:17 bypass verbose 76 0 33552384 dust 252:17 bypass verbose
77 77
78 $ sudo dd if=/dev/mapper/dust1 of=/dev 78 $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct
79 128+0 records in 79 128+0 records in
80 128+0 records out 80 128+0 records out
81 81
82 $ sudo dd if=/dev/zero of=/dev/mapper/ 82 $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
83 128+0 records in 83 128+0 records in
84 128+0 records out 84 128+0 records out
85 85
86 Adding and removing bad blocks 86 Adding and removing bad blocks
87 ------------------------------ 87 ------------------------------
88 88
89 At any time (i.e.: whether the device has the 89 At any time (i.e.: whether the device has the "bad block" emulation
90 enabled or disabled), bad blocks may be added 90 enabled or disabled), bad blocks may be added or removed from the
91 device via the "addbadblock" and "removebadblo 91 device via the "addbadblock" and "removebadblock" messages::
92 92
93 $ sudo dmsetup message dust1 0 addbadb 93 $ sudo dmsetup message dust1 0 addbadblock 60
94 kernel: device-mapper: dust: badblock 94 kernel: device-mapper: dust: badblock added at block 60
95 95
96 $ sudo dmsetup message dust1 0 addbadb 96 $ sudo dmsetup message dust1 0 addbadblock 67
97 kernel: device-mapper: dust: badblock 97 kernel: device-mapper: dust: badblock added at block 67
98 98
99 $ sudo dmsetup message dust1 0 addbadb 99 $ sudo dmsetup message dust1 0 addbadblock 72
100 kernel: device-mapper: dust: badblock 100 kernel: device-mapper: dust: badblock added at block 72
101 101
102 These bad blocks will be stored in the "bad bl 102 These bad blocks will be stored in the "bad block list".
103 While the device is in "bypass" mode, reads an 103 While the device is in "bypass" mode, reads and writes will succeed::
104 104
105 $ sudo dmsetup status dust1 105 $ sudo dmsetup status dust1
106 0 33552384 dust 252:17 bypass 106 0 33552384 dust 252:17 bypass
107 107
108 Enabling block read failures 108 Enabling block read failures
109 ---------------------------- 109 ----------------------------
110 110
111 To enable the "fail read on bad block" behavio 111 To enable the "fail read on bad block" behavior, send the "enable" message::
112 112
113 $ sudo dmsetup message dust1 0 enable 113 $ sudo dmsetup message dust1 0 enable
114 kernel: device-mapper: dust: enabling 114 kernel: device-mapper: dust: enabling read failures on bad sectors
115 115
116 $ sudo dmsetup status dust1 116 $ sudo dmsetup status dust1
117 0 33552384 dust 252:17 fail_read_on_ba 117 0 33552384 dust 252:17 fail_read_on_bad_block
118 118
119 With the device in "fail read on bad block" mo 119 With the device in "fail read on bad block" mode, attempting to read a
120 block will encounter an "Input/output error":: 120 block will encounter an "Input/output error"::
121 121
122 $ sudo dd if=/dev/mapper/dust1 of=/dev 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': 123 dd: error reading '/dev/mapper/dust1': Input/output error
124 0+0 records in 124 0+0 records in
125 0+0 records out 125 0+0 records out
126 0 bytes copied, 0.00040651 s, 0.0 kB/s 126 0 bytes copied, 0.00040651 s, 0.0 kB/s
127 127
128 ...and writing to the bad blocks will remove t 128 ...and writing to the bad blocks will remove the blocks from the list,
129 therefore emulating the "remap" behavior of ha 129 therefore emulating the "remap" behavior of hard disk drives::
130 130
131 $ sudo dd if=/dev/zero of=/dev/mapper/ 131 $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
132 128+0 records in 132 128+0 records in
133 128+0 records out 133 128+0 records out
134 134
135 kernel: device-mapper: dust: block 60 135 kernel: device-mapper: dust: block 60 removed from badblocklist by write
136 kernel: device-mapper: dust: block 67 136 kernel: device-mapper: dust: block 67 removed from badblocklist by write
137 kernel: device-mapper: dust: block 72 137 kernel: device-mapper: dust: block 72 removed from badblocklist by write
138 kernel: device-mapper: dust: block 87 138 kernel: device-mapper: dust: block 87 removed from badblocklist by write
139 139
140 Bad block add/remove error handling 140 Bad block add/remove error handling
141 ----------------------------------- 141 -----------------------------------
142 142
143 Attempting to add a bad block that already exi 143 Attempting to add a bad block that already exists in the list will
144 result in an "Invalid argument" error, as well 144 result in an "Invalid argument" error, as well as a helpful message::
145 145
146 $ sudo dmsetup message dust1 0 addbadb 146 $ sudo dmsetup message dust1 0 addbadblock 88
147 device-mapper: message ioctl on dust1 147 device-mapper: message ioctl on dust1 failed: Invalid argument
148 kernel: device-mapper: dust: block 88 148 kernel: device-mapper: dust: block 88 already in badblocklist
149 149
150 Attempting to remove a bad block that doesn't 150 Attempting to remove a bad block that doesn't exist in the list will
151 result in an "Invalid argument" error, as well 151 result in an "Invalid argument" error, as well as a helpful message::
152 152
153 $ sudo dmsetup message dust1 0 removeb 153 $ sudo dmsetup message dust1 0 removebadblock 87
154 device-mapper: message ioctl on dust1 154 device-mapper: message ioctl on dust1 failed: Invalid argument
155 kernel: device-mapper: dust: block 87 155 kernel: device-mapper: dust: block 87 not found in badblocklist
156 156
157 Counting the number of bad blocks in the bad b 157 Counting the number of bad blocks in the bad block list
158 ---------------------------------------------- 158 -------------------------------------------------------
159 159
160 To count the number of bad blocks configured i 160 To count the number of bad blocks configured in the device, run the
161 following message command:: 161 following message command::
162 162
163 $ sudo dmsetup message dust1 0 countba 163 $ sudo dmsetup message dust1 0 countbadblocks
164 164
165 A message will print with the number of bad bl 165 A message will print with the number of bad blocks currently
166 configured on the device:: 166 configured on the device::
167 167
168 countbadblocks: 895 badblock(s) found 168 countbadblocks: 895 badblock(s) found
169 169
170 Querying for specific bad blocks 170 Querying for specific bad blocks
171 -------------------------------- 171 --------------------------------
172 172
173 To find out if a specific block is in the bad 173 To find out if a specific block is in the bad block list, run the
174 following message command:: 174 following message command::
175 175
176 $ sudo dmsetup message dust1 0 querybl 176 $ sudo dmsetup message dust1 0 queryblock 72
177 177
178 The following message will print if the block 178 The following message will print if the block is in the list::
179 179
180 dust_query_block: block 72 found in ba 180 dust_query_block: block 72 found in badblocklist
181 181
182 The following message will print if the block 182 The following message will print if the block is not in the list::
183 183
184 dust_query_block: block 72 not found i 184 dust_query_block: block 72 not found in badblocklist
185 185
186 The "queryblock" message command will work in 186 The "queryblock" message command will work in both the "enabled"
187 and "disabled" modes, allowing the verificatio 187 and "disabled" modes, allowing the verification of whether a block
188 will be treated as "bad" without having to iss 188 will be treated as "bad" without having to issue I/O to the device,
189 or having to "enable" the bad block emulation. 189 or having to "enable" the bad block emulation.
190 190
191 Clearing the bad block list 191 Clearing the bad block list
192 --------------------------- 192 ---------------------------
193 193
194 To clear the bad block list (without needing t 194 To clear the bad block list (without needing to individually run
195 a "removebadblock" message command for every b 195 a "removebadblock" message command for every block), run the
196 following message command:: 196 following message command::
197 197
198 $ sudo dmsetup message dust1 0 clearba 198 $ sudo dmsetup message dust1 0 clearbadblocks
199 199
200 After clearing the bad block list, the followi 200 After clearing the bad block list, the following message will appear::
201 201
202 dust_clear_badblocks: badblocks cleare 202 dust_clear_badblocks: badblocks cleared
203 203
204 If there were no bad blocks to clear, the foll 204 If there were no bad blocks to clear, the following message will
205 appear:: 205 appear::
206 206
207 dust_clear_badblocks: no badblocks fou 207 dust_clear_badblocks: no badblocks found
208 208
209 Listing the bad block list 209 Listing the bad block list
210 -------------------------- 210 --------------------------
211 211
212 To list all bad blocks in the bad block list ( 212 To list all bad blocks in the bad block list (using an example device
213 with blocks 1 and 2 in the bad block list), ru 213 with blocks 1 and 2 in the bad block list), run the following message
214 command:: 214 command::
215 215
216 $ sudo dmsetup message dust1 0 listbad 216 $ sudo dmsetup message dust1 0 listbadblocks
217 1 217 1
218 2 218 2
219 219
220 If there are no bad blocks in the bad block li 220 If there are no bad blocks in the bad block list, the command will
221 execute with no output:: 221 execute with no output::
222 222
223 $ sudo dmsetup message dust1 0 listbad 223 $ sudo dmsetup message dust1 0 listbadblocks
224 224
225 Message commands list 225 Message commands list
226 --------------------- 226 ---------------------
227 227
228 Below is a list of the messages that can be se 228 Below is a list of the messages that can be sent to a dust device:
229 229
230 Operations on blocks (requires a <blknum> argu 230 Operations on blocks (requires a <blknum> argument)::
231 231
232 addbadblock <blknum> 232 addbadblock <blknum>
233 queryblock <blknum> 233 queryblock <blknum>
234 removebadblock <blknum> 234 removebadblock <blknum>
235 235
236 ...where <blknum> is a block number within ran 236 ...where <blknum> is a block number within range of the device
237 (corresponding to the block size of the device 237 (corresponding to the block size of the device.)
238 238
239 Single argument message commands:: 239 Single argument message commands::
240 240
241 countbadblocks 241 countbadblocks
242 clearbadblocks 242 clearbadblocks
243 listbadblocks 243 listbadblocks
244 disable 244 disable
245 enable 245 enable
246 quiet 246 quiet
247 247
248 Device removal 248 Device removal
249 -------------- 249 --------------
250 250
251 When finished, remove the device via the "dmse 251 When finished, remove the device via the "dmsetup remove" command::
252 252
253 $ sudo dmsetup remove dust1 253 $ sudo dmsetup remove dust1
254 254
255 Quiet mode 255 Quiet mode
256 ---------- 256 ----------
257 257
258 On test runs with many bad blocks, it may be d 258 On test runs with many bad blocks, it may be desirable to avoid
259 excessive logging (from bad blocks added, remo 259 excessive logging (from bad blocks added, removed, or "remapped").
260 This can be done by enabling "quiet mode" via 260 This can be done by enabling "quiet mode" via the following message::
261 261
262 $ sudo dmsetup message dust1 0 quiet 262 $ sudo dmsetup message dust1 0 quiet
263 263
264 This will suppress log messages from add / rem 264 This will suppress log messages from add / remove / removed by write
265 operations. Log messages from "countbadblocks 265 operations. Log messages from "countbadblocks" or "queryblock"
266 message commands will still print in quiet mod 266 message commands will still print in quiet mode.
267 267
268 The status of quiet mode can be seen by runnin 268 The status of quiet mode can be seen by running "dmsetup status"::
269 269
270 $ sudo dmsetup status dust1 270 $ sudo dmsetup status dust1
271 0 33552384 dust 252:17 fail_read_on_ba 271 0 33552384 dust 252:17 fail_read_on_bad_block quiet
272 272
273 To disable quiet mode, send the "quiet" messag 273 To disable quiet mode, send the "quiet" message again::
274 274
275 $ sudo dmsetup message dust1 0 quiet 275 $ sudo dmsetup message dust1 0 quiet
276 276
277 $ sudo dmsetup status dust1 277 $ sudo dmsetup status dust1
278 0 33552384 dust 252:17 fail_read_on_ba 278 0 33552384 dust 252:17 fail_read_on_bad_block verbose
279 279
280 (The presence of "verbose" indicates normal lo 280 (The presence of "verbose" indicates normal logging.)
281 281
282 "Why not...?" 282 "Why not...?"
283 ------------- 283 -------------
284 284
285 scsi_debug has a "medium error" mode that can 285 scsi_debug has a "medium error" mode that can fail reads on one
286 specified sector (sector 0x1234, hardcoded in 286 specified sector (sector 0x1234, hardcoded in the source code), but
287 it uses RAM for the persistent storage, which 287 it uses RAM for the persistent storage, which drastically decreases
288 the potential device size. 288 the potential device size.
289 289
290 dm-flakey fails all I/O from all block locatio 290 dm-flakey fails all I/O from all block locations at a specified time
291 frequency, and not a given point in time. 291 frequency, and not a given point in time.
292 292
293 When a bad sector occurs on a hard disk drive, 293 When a bad sector occurs on a hard disk drive, reads to that sector
294 are failed by the device, usually resulting in 294 are failed by the device, usually resulting in an error code of EIO
295 ("I/O error") or ENODATA ("No data available") 295 ("I/O error") or ENODATA ("No data available"). However, a write to
296 the sector may succeed, and result in the sect 296 the sector may succeed, and result in the sector becoming readable
297 after the device controller no longer experien 297 after the device controller no longer experiences errors reading the
298 sector (or after a reallocation of the sector) 298 sector (or after a reallocation of the sector). However, there may
299 be bad sectors that occur on the device in the 299 be bad sectors that occur on the device in the future, in a different,
300 unpredictable location. 300 unpredictable location.
301 301
302 This target seeks to provide a device that can 302 This target seeks to provide a device that can exhibit the behavior
303 of a bad sector at a known sector location, at 303 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 304 on a large storage device (at least tens of gigabytes, not occupying
305 system memory). 305 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.