Documentation/fault-injection/fault-injection.txt

   1 Fault injection capabilities infrastructure
   2 ===========================================
   3
   4 See also drivers/md/faulty.c and "every_nth" module option for scsi_debug.
   5
   6
   7 Available fault injection capabilities
   8 --------------------------------------
   9
  10 o failslab
  11
  12   injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...)
  13
  14 o fail_page_alloc
  15
  16   injects page allocation failures. (alloc_pages(), get_free_pages(), ...)
  17
  18 o fail_make_request
  19
  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())
  23
  24 Configure fault-injection capabilities behavior
  25 -----------------------------------------------
  26
  27 o debugfs entries
  28
  29 fault-inject-debugfs kernel module provides some debugfs entries for runtime
  30 configuration of fault-injection capabilities.
  31
  32 - /debug/*/probability:
  33
  34         likelihood of failure injection, in percent.
  35         Format: <percent>
  36
  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.
  40
  41 - /debug/*/interval:
  42
  43         specifies the interval between failures, for calls to
  44         should_fail() that pass all the other tests.
  45
  46         Note that if you enable this, by setting interval>1, you will
  47         probably want to set probability=100.
  48
  49 - /debug/*/times:
  50
  51         specifies how many times failures may happen at most.
  52         A value of -1 means "no limit".
  53
  54 - /debug/*/space:
  55
  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.
  59
  60 - /debug/*/verbose
  61
  62         Format: { 0 | 1 | 2 }
  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
  67         capabilities.
  68
  69 - /debug/*/task-filter:
  70
  71         Format: { 0 | 1 }
  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.
  75
  76 - /debug/*/address-start:
  77 - /debug/*/address-end:
  78
  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).
  83
  84 - /debug/*/stacktrace-depth:
  85
  86         specifies the maximum stacktrace depth walked during search
  87         for a caller within [address-start,address-end).
  88
  89 - /debug/fail_page_alloc/ignore-gfp-highmem:
  90
  91         Format: { 0 | 1 }
  92         default is 0, setting it to '1' won't inject failures into
  93         highmem/user allocations.
  94
  95 - /debug/failslab/ignore-gfp-wait:
  96 - /debug/fail_page_alloc/ignore-gfp-wait:
  97
  98         Format: { 0 | 1 }
  99         default is 0, setting it to '1' will inject failures
 100         only into non-sleep allocations (GFP_ATOMIC allocations).
 101
 102 o Boot option
 103
 104 In order to inject faults while debugfs is not available (early boot time),
 105 use the boot option:
 106
 107         failslab=
 108         fail_page_alloc=
 109         fail_make_request=<interval>,<probability>,<space>,<times>
 110
 111 How to add new fault injection capability
 112 -----------------------------------------
 113
 114 o #include <linux/fault-inject.h>
 115
 116 o define the fault attributes
 117
 118   DECLARE_FAULT_INJECTION(name);
 119
 120   Please see the definition of struct fault_attr in fault-inject.h
 121   for details.
 122
 123 o provide the way to configure fault attributes
 124
 125 - boot option
 126
 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.
 129
 130   setup_fault_attr(attr, str);
 131
 132 - debugfs entries
 133
 134   failslab, fail_page_alloc, and fail_make_request use this way.
 135   There is a helper function for it.
 136
 137   init_fault_attr_entries(entries, attr, name);
 138   void cleanup_fault_attr_entries(entries);
 139
 140 - module parameters
 141
 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.
 145
 146 o add a hook to insert failures
 147
 148   should_fail() returns 1 when failures should happen.
 149
 150         should_fail(attr,size);
 151
 152 Application Examples
 153 --------------------
 154
 155 o inject slab allocation failures into module init/cleanup code
 156
 157 ------------------------------------------------------------------------------
 158 #!/bin/bash
 159
 160 FAILCMD=Documentation/fault-injection/failcmd.sh
 161 BLACKLIST="root_plug evbug"
 162
 163 FAILNAME=failslab
 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
 170
 171 blacklist()
 172 {
 173         echo $BLACKLIST | grep $1 > /dev/null 2>&1
 174 }
 175
 176 oops()
 177 {
 178         dmesg | grep BUG > /dev/null 2>&1
 179 }
 180
 181 find /lib/modules/`uname -r` -name '*.ko' -exec basename {} .ko \; |
 182         while read i
 183         do
 184                 oops && exit 1
 185
 186                 if ! blacklist $i
 187                 then
 188                         echo inserting $i...
 189                         bash $FAILCMD modprobe $i
 190                 fi
 191         done
 192
 193 lsmod | awk '{ if ($3 == 0) { print $1 } }' |
 194         while read i
 195         do
 196                 oops && exit 1
 197
 198                 if ! blacklist $i
 199                 then
 200                         echo removing $i...
 201                         bash $FAILCMD modprobe -r $i
 202                 fi
 203         done
 204
 205 ------------------------------------------------------------------------------
 206
 207 o inject slab allocation failures only for a specific module
 208
 209 ------------------------------------------------------------------------------
 210 #!/bin/bash
 211
 212 FAILMOD=Documentation/fault-injection/failmodule.sh
 213
 214 echo injecting errors into the module $1...
 215
 216 modprobe $1
 217 bash $FAILMOD failslab $1 10
 218 echo 25 > /debug/failslab/probability
 219
 220 ------------------------------------------------------------------------------
 221