1 Fault injection capabilities infrastructure
2 ===========================================
4 See also drivers/md/faulty.c and "every_nth" module option for scsi_debug.
7 Available fault injection capabilities
8 --------------------------------------
12 injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...)
16 injects page allocation failures. (alloc_pages(), get_free_pages(), ...)
20 injects futex deadlock and uaddr fault errors.
24 injects disk IO errors on devices permitted by setting
25 /sys/block/<device>/make-it-fail or
26 /sys/block/<device>/<partition>/make-it-fail. (generic_make_request())
30 injects MMC data errors on devices permitted by setting
31 debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request
33 Configure fault-injection capabilities behavior
34 -----------------------------------------------
38 fault-inject-debugfs kernel module provides some debugfs entries for runtime
39 configuration of fault-injection capabilities.
41 - /sys/kernel/debug/fail*/probability:
43 likelihood of failure injection, in percent.
46 Note that one-failure-per-hundred is a very high error rate
47 for some testcases. Consider setting probability=100 and configure
48 /sys/kernel/debug/fail*/interval for such testcases.
50 - /sys/kernel/debug/fail*/interval:
52 specifies the interval between failures, for calls to
53 should_fail() that pass all the other tests.
55 Note that if you enable this, by setting interval>1, you will
56 probably want to set probability=100.
58 - /sys/kernel/debug/fail*/times:
60 specifies how many times failures may happen at most.
61 A value of -1 means "no limit".
63 - /sys/kernel/debug/fail*/space:
65 specifies an initial resource "budget", decremented by "size"
66 on each call to should_fail(,size). Failure injection is
67 suppressed until "space" reaches zero.
69 - /sys/kernel/debug/fail*/verbose
72 specifies the verbosity of the messages when failure is
73 injected. '0' means no messages; '1' will print only a single
74 log line per failure; '2' will print a call trace too -- useful
75 to debug the problems revealed by fault injection.
77 - /sys/kernel/debug/fail*/task-filter:
80 A value of 'N' disables filtering by process (default).
81 Any positive value limits failures to only processes indicated by
82 /proc/<pid>/make-it-fail==1.
84 - /sys/kernel/debug/fail*/require-start:
85 - /sys/kernel/debug/fail*/require-end:
86 - /sys/kernel/debug/fail*/reject-start:
87 - /sys/kernel/debug/fail*/reject-end:
89 specifies the range of virtual addresses tested during
90 stacktrace walking. Failure is injected only if some caller
91 in the walked stacktrace lies within the required range, and
92 none lies within the rejected range.
93 Default required range is [0,ULONG_MAX) (whole of virtual address space).
94 Default rejected range is [0,0).
96 - /sys/kernel/debug/fail*/stacktrace-depth:
98 specifies the maximum stacktrace depth walked during search
99 for a caller within [require-start,require-end) OR
100 [reject-start,reject-end).
102 - /sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem:
104 Format: { 'Y' | 'N' }
105 default is 'N', setting it to 'Y' won't inject failures into
106 highmem/user allocations.
108 - /sys/kernel/debug/failslab/ignore-gfp-wait:
109 - /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait:
111 Format: { 'Y' | 'N' }
112 default is 'N', setting it to 'Y' will inject failures
113 only into non-sleep allocations (GFP_ATOMIC allocations).
115 - /sys/kernel/debug/fail_page_alloc/min-order:
117 specifies the minimum page allocation order to be injected
120 - /sys/kernel/debug/fail_futex/ignore-private:
122 Format: { 'Y' | 'N' }
123 default is 'N', setting it to 'Y' will disable failure injections
124 when dealing with private (address space) futexes.
128 In order to inject faults while debugfs is not available (early boot time),
135 mmc_core.fail_request=<interval>,<probability>,<space>,<times>
139 - /proc/self/task/<current-tid>/fail-nth:
141 Write to this file of integer N makes N-th call in the task fail.
142 Read from this file returns a integer value. A value of '0' indicates
143 that the fault setup with a previous write to this file was injected.
144 A positive integer N indicates that the fault wasn't yet injected.
145 Note that this file enables all types of faults (slab, futex, etc).
146 This setting takes precedence over all other generic debugfs settings
147 like probability, interval, times, etc. But per-capability settings
148 (e.g. fail_futex/ignore-private) take precedence over it.
150 This feature is intended for systematic testing of faults in a single
151 system call. See an example below.
153 How to add new fault injection capability
154 -----------------------------------------
156 o #include <linux/fault-inject.h>
158 o define the fault attributes
160 DECLARE_FAULT_INJECTION(name);
162 Please see the definition of struct fault_attr in fault-inject.h
165 o provide a way to configure fault attributes
169 If you need to enable the fault injection capability from boot time, you can
170 provide boot option to configure it. There is a helper function for it:
172 setup_fault_attr(attr, str);
176 failslab, fail_page_alloc, and fail_make_request use this way.
179 fault_create_debugfs_attr(name, parent, attr);
183 If the scope of the fault injection capability is limited to a
184 single kernel module, it is better to provide module parameters to
185 configure the fault attributes.
187 o add a hook to insert failures
189 Upon should_fail() returning true, client code should inject a failure.
191 should_fail(attr, size);
196 o Inject slab allocation failures into module init/exit code
201 echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
202 echo 10 > /sys/kernel/debug/$FAILTYPE/probability
203 echo 100 > /sys/kernel/debug/$FAILTYPE/interval
204 echo -1 > /sys/kernel/debug/$FAILTYPE/times
205 echo 0 > /sys/kernel/debug/$FAILTYPE/space
206 echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
207 echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
211 bash -c "echo 1 > /proc/self/make-it-fail && exec $*"
216 echo "Usage: $0 modulename [ modulename ... ]"
223 faulty_system modprobe $m
226 faulty_system modprobe -r $m
229 ------------------------------------------------------------------------------
231 o Inject page allocation failures only for a specific module
235 FAILTYPE=fail_page_alloc
240 echo "Usage: $0 <modulename>"
246 if [ ! -d /sys/module/$module/sections ]
248 echo Module $module is not loaded
252 cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
253 cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
255 echo N > /sys/kernel/debug/$FAILTYPE/task-filter
256 echo 10 > /sys/kernel/debug/$FAILTYPE/probability
257 echo 100 > /sys/kernel/debug/$FAILTYPE/interval
258 echo -1 > /sys/kernel/debug/$FAILTYPE/times
259 echo 0 > /sys/kernel/debug/$FAILTYPE/space
260 echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
261 echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
262 echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
263 echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
265 trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
267 echo "Injecting errors into the module $module... (interrupt to stop)"
270 Tool to run command with failslab or fail_page_alloc
271 ----------------------------------------------------
272 In order to make it easier to accomplish the tasks mentioned above, we can use
273 tools/testing/fault-injection/failcmd.sh. Please run a command
274 "./tools/testing/fault-injection/failcmd.sh --help" for more information and
275 see the following examples.
279 Run a command "make -C tools/testing/selftests/ run_tests" with injecting slab
282 # ./tools/testing/fault-injection/failcmd.sh \
283 -- make -C tools/testing/selftests/ run_tests
285 Same as above except to specify 100 times failures at most instead of one time
288 # ./tools/testing/fault-injection/failcmd.sh --times=100 \
289 -- make -C tools/testing/selftests/ run_tests
291 Same as above except to inject page allocation failure instead of slab
294 # env FAILCMD_TYPE=fail_page_alloc \
295 ./tools/testing/fault-injection/failcmd.sh --times=100 \
296 -- make -C tools/testing/selftests/ run_tests
298 Systematic faults using fail-nth
299 ---------------------------------
301 The following code systematically faults 0-th, 1-st, 2-nd and so on
302 capabilities in the socketpair() system call.
304 #include <sys/types.h>
305 #include <sys/stat.h>
306 #include <sys/socket.h>
307 #include <sys/syscall.h>
317 int i, err, res, fail_nth, fds[2];
320 system("echo N > /sys/kernel/debug/failslab/ignore-gfp-wait");
321 sprintf(buf, "/proc/self/task/%ld/fail-nth", syscall(SYS_gettid));
322 fail_nth = open(buf, O_RDWR);
324 sprintf(buf, "%d", i);
325 write(fail_nth, buf, strlen(buf));
326 res = socketpair(AF_LOCAL, SOCK_STREAM, 0, fds);
328 pread(fail_nth, buf, sizeof(buf), 0);
333 printf("%d-th fault %c: res=%d/%d\n", i, atoi(buf) ? 'N' : 'Y',
343 1-th fault Y: res=-1/23
344 2-th fault Y: res=-1/23
345 3-th fault Y: res=-1/12
346 4-th fault Y: res=-1/12
347 5-th fault Y: res=-1/23
348 6-th fault Y: res=-1/23
349 7-th fault Y: res=-1/23
350 8-th fault Y: res=-1/12
351 9-th fault Y: res=-1/12
352 10-th fault Y: res=-1/12
353 11-th fault Y: res=-1/12
354 12-th fault Y: res=-1/12
355 13-th fault Y: res=-1/12
356 14-th fault Y: res=-1/12
357 15-th fault Y: res=-1/12
358 16-th fault N: res=0/12