xref: /linux/Documentation/admin-guide/device-mapper/dm-dust.rst (revision 26fbb4c8c7c3ee9a4c3b4de555a8587b5a19154e)
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