xen: cleancache shim to Xen Transcendent Memory
[linux-2.6/next.git] / Documentation / fault-injection / fault-injection.txt
blob7be15e44d48166246cd85c99e8219b08e0fce52c
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 --------------------------------------
10 o failslab
12   injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...)
14 o fail_page_alloc
16   injects page allocation failures. (alloc_pages(), get_free_pages(), ...)
18 o fail_make_request
20   injects disk IO errors on devices permitted by setting
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 -----------------------------------------------
27 o debugfs entries
29 fault-inject-debugfs kernel module provides some debugfs entries for runtime
30 configuration of fault-injection capabilities.
32 - /sys/kernel/debug/fail*/probability:
34         likelihood of failure injection, in percent.
35         Format: <percent>
37         Note that one-failure-per-hundred is a very high error rate
38         for some testcases.  Consider setting probability=100 and configure
39         /sys/kernel/debug/fail*/interval for such testcases.
41 - /sys/kernel/debug/fail*/interval:
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.
49 - /sys/kernel/debug/fail*/times:
51         specifies how many times failures may happen at most.
52         A value of -1 means "no limit".
54 - /sys/kernel/debug/fail*/space:
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.
60 - /sys/kernel/debug/fail*/verbose
62         Format: { 0 | 1 | 2 }
63         specifies the verbosity of the messages when failure is
64         injected.  '0' means no messages; '1' will print only a single
65         log line per failure; '2' will print a call trace too -- useful
66         to debug the problems revealed by fault injection.
68 - /sys/kernel/debug/fail*/task-filter:
70         Format: { 'Y' | 'N' }
71         A value of 'N' disables filtering by process (default).
72         Any positive value limits failures to only processes indicated by
73         /proc/<pid>/make-it-fail==1.
75 - /sys/kernel/debug/fail*/require-start:
76 - /sys/kernel/debug/fail*/require-end:
77 - /sys/kernel/debug/fail*/reject-start:
78 - /sys/kernel/debug/fail*/reject-end:
80         specifies the range of virtual addresses tested during
81         stacktrace walking.  Failure is injected only if some caller
82         in the walked stacktrace lies within the required range, and
83         none lies within the rejected range.
84         Default required range is [0,ULONG_MAX) (whole of virtual address space).
85         Default rejected range is [0,0).
87 - /sys/kernel/debug/fail*/stacktrace-depth:
89         specifies the maximum stacktrace depth walked during search
90         for a caller within [require-start,require-end) OR
91         [reject-start,reject-end).
93 - /sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem:
95         Format: { 'Y' | 'N' }
96         default is 'N', setting it to 'Y' won't inject failures into
97         highmem/user allocations.
99 - /sys/kernel/debug/failslab/ignore-gfp-wait:
100 - /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait:
102         Format: { 'Y' | 'N' }
103         default is 'N', setting it to 'Y' will inject failures
104         only into non-sleep allocations (GFP_ATOMIC allocations).
106 - /sys/kernel/debug/fail_page_alloc/min-order:
108         specifies the minimum page allocation order to be injected
109         failures.
111 o Boot option
113 In order to inject faults while debugfs is not available (early boot time),
114 use the boot option:
116         failslab=
117         fail_page_alloc=
118         fail_make_request=<interval>,<probability>,<space>,<times>
120 How to add new fault injection capability
121 -----------------------------------------
123 o #include <linux/fault-inject.h>
125 o define the fault attributes
127   DECLARE_FAULT_INJECTION(name);
129   Please see the definition of struct fault_attr in fault-inject.h
130   for details.
132 o provide a way to configure fault attributes
134 - boot option
136   If you need to enable the fault injection capability from boot time, you can
137   provide boot option to configure it. There is a helper function for it:
139         setup_fault_attr(attr, str);
141 - debugfs entries
143   failslab, fail_page_alloc, and fail_make_request use this way.
144   Helper functions:
146         init_fault_attr_dentries(entries, attr, name);
147         void cleanup_fault_attr_dentries(entries);
149 - module parameters
151   If the scope of the fault injection capability is limited to a
152   single kernel module, it is better to provide module parameters to
153   configure the fault attributes.
155 o add a hook to insert failures
157   Upon should_fail() returning true, client code should inject a failure.
159         should_fail(attr, size);
161 Application Examples
162 --------------------
164 o Inject slab allocation failures into module init/exit code
166 #!/bin/bash
168 FAILTYPE=failslab
169 echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
170 echo 10 > /sys/kernel/debug/$FAILTYPE/probability
171 echo 100 > /sys/kernel/debug/$FAILTYPE/interval
172 echo -1 > /sys/kernel/debug/$FAILTYPE/times
173 echo 0 > /sys/kernel/debug/$FAILTYPE/space
174 echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
175 echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
177 faulty_system()
179         bash -c "echo 1 > /proc/self/make-it-fail && exec $*"
182 if [ $# -eq 0 ]
183 then
184         echo "Usage: $0 modulename [ modulename ... ]"
185         exit 1
188 for m in $*
190         echo inserting $m...
191         faulty_system modprobe $m
193         echo removing $m...
194         faulty_system modprobe -r $m
195 done
197 ------------------------------------------------------------------------------
199 o Inject page allocation failures only for a specific module
201 #!/bin/bash
203 FAILTYPE=fail_page_alloc
204 module=$1
206 if [ -z $module ]
207 then
208         echo "Usage: $0 <modulename>"
209         exit 1
212 modprobe $module
214 if [ ! -d /sys/module/$module/sections ]
215 then
216         echo Module $module is not loaded
217         exit 1
220 cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
221 cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
223 echo N > /sys/kernel/debug/$FAILTYPE/task-filter
224 echo 10 > /sys/kernel/debug/$FAILTYPE/probability
225 echo 100 > /sys/kernel/debug/$FAILTYPE/interval
226 echo -1 > /sys/kernel/debug/$FAILTYPE/times
227 echo 0 > /sys/kernel/debug/$FAILTYPE/space
228 echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
229 echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
230 echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
231 echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
233 trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
235 echo "Injecting errors into the module $module... (interrupt to stop)"
236 sleep 1000000