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 disk IO errors on permitted devices by
21 /sys/block/<device>/make-it-fail or
22 /sys/block/<device>/<partition>/make-it-fail. (generic_make_request())
24 Configure fault-injection capabilities behavior
25 -----------------------------------------------
29 fault-inject-debugfs kernel module provides some debugfs entries for runtime
30 configuration of fault-injection capabilities.
32 - /debug/*/probability:
34 likelihood of failure injection, in percent.
37 Note that one-failure-per-handred is a very high error rate
38 for some testcases. Please set probably=100 and configure
39 /debug/*/interval for such testcases.
43 specifies the interval between failures, for calls to
44 should_fail() that pass all the other tests.
46 Note that if you enable this, by setting interval>1, you will
47 probably want to set probability=100.
51 specifies how many times failures may happen at most.
52 A value of -1 means "no limit".
56 specifies an initial resource "budget", decremented by "size"
57 on each call to should_fail(,size). Failure injection is
58 suppressed until "space" reaches zero.
63 specifies the verbosity of the messages when failure is injected.
64 We default to 0 (no extra messages), setting it to '1' will
65 print only to tell failure happened, '2' will print call trace too -
66 it is useful to debug the problems revealed by fault injection
69 - /debug/*/task-filter:
72 A value of '0' disables filtering by process (default).
73 Any positive value limits failures to only processes indicated by
74 /proc/<pid>/make-it-fail==1.
76 - /debug/*/address-start:
77 - /debug/*/address-end:
79 specifies the range of virtual addresses tested during
80 stacktrace walking. Failure is injected only if some caller
81 in the walked stacktrace lies within this range.
82 Default is [0,ULONG_MAX) (whole of virtual address space).
84 - /debug/*/stacktrace-depth:
86 specifies the maximum stacktrace depth walked during search
87 for a caller within [address-start,address-end).
89 - /debug/fail_page_alloc/ignore-gfp-highmem:
92 default is 0, setting it to '1' won't inject failures into
93 highmem/user allocations.
95 - /debug/failslab/ignore-gfp-wait:
96 - /debug/fail_page_alloc/ignore-gfp-wait:
99 default is 0, setting it to '1' will inject failures
100 only into non-sleep allocations (GFP_ATOMIC allocations).
104 In order to inject faults while debugfs is not available (early boot time),
109 fail_make_request=<interval>,<probability>,<space>,<times>
111 How to add new fault injection capability
112 -----------------------------------------
114 o #include <linux/fault-inject.h>
116 o define the fault attributes
118 DECLARE_FAULT_INJECTION(name);
120 Please see the definition of struct fault_attr in fault-inject.h
123 o provide the way to configure fault attributes
127 If you need to enable the fault injection capability from boot time, you can
128 provide boot option to configure it. There is a helper function for it.
130 setup_fault_attr(attr, str);
134 failslab, fail_page_alloc, and fail_make_request use this way.
135 There is a helper function for it.
137 init_fault_attr_entries(entries, attr, name);
138 void cleanup_fault_attr_entries(entries);
142 If the scope of the fault injection capability is limited to a
143 single kernel module, it is better to provide module parameters to
144 configure the fault attributes.
146 o add a hook to insert failures
148 should_fail() returns 1 when failures should happen.
150 should_fail(attr,size);
155 o inject slab allocation failures into module init/cleanup code
157 ------------------------------------------------------------------------------
160 FAILCMD=Documentation/fault-injection/failcmd.sh
161 BLACKLIST="root_plug evbug"
164 echo Y > /debug/$FAILNAME/task-filter
165 echo 10 > /debug/$FAILNAME/probability
166 echo 100 > /debug/$FAILNAME/interval
167 echo -1 > /debug/$FAILNAME/times
168 echo 2 > /debug/$FAILNAME/verbose
169 echo 1 > /debug/$FAILNAME/ignore-gfp-wait
173 echo $BLACKLIST | grep $1 > /dev/null 2>&1
178 dmesg | grep BUG > /dev/null 2>&1
181 find /lib/modules/`uname -r` -name '*.ko' -exec basename {} .ko \; |
189 bash $FAILCMD modprobe $i
193 lsmod | awk '{ if ($3 == 0) { print $1 } }' |
201 bash $FAILCMD modprobe -r $i
205 ------------------------------------------------------------------------------
207 o inject slab allocation failures only for a specific module
209 ------------------------------------------------------------------------------
212 FAILMOD=Documentation/fault-injection/failmodule.sh
214 echo injecting errors into the module $1...
217 bash $FAILMOD failslab $1 10
218 echo 25 > /debug/failslab/probability
220 ------------------------------------------------------------------------------