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_futex
  19
  20   injects futex deadlock and uaddr fault errors.
  21
  22 o fail_make_request
  23
  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())
  27
  28 o fail_mmc_request
  29
  30   injects MMC data errors on devices permitted by setting
  31   debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request
  32
  33 Configure fault-injection capabilities behavior
  34 -----------------------------------------------
  35
  36 o debugfs entries
  37
  38 fault-inject-debugfs kernel module provides some debugfs entries for runtime
  39 configuration of fault-injection capabilities.
  40
  41 - /sys/kernel/debug/fail*/probability:
  42
  43         likelihood of failure injection, in percent.
  44         Format: <percent>
  45
  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.
  49
  50 - /sys/kernel/debug/fail*/interval:
  51
  52         specifies the interval between failures, for calls to
  53         should_fail() that pass all the other tests.
  54
  55         Note that if you enable this, by setting interval>1, you will
  56         probably want to set probability=100.
  57
  58 - /sys/kernel/debug/fail*/times:
  59
  60         specifies how many times failures may happen at most.
  61         A value of -1 means "no limit".
  62
  63 - /sys/kernel/debug/fail*/space:
  64
  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.
  68
  69 - /sys/kernel/debug/fail*/verbose
  70
  71         Format: { 0 | 1 | 2 }
  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.
  76
  77 - /sys/kernel/debug/fail*/task-filter:
  78
  79         Format: { 'Y' | 'N' }
  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.
  83
  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:
  88
  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).
  95
  96 - /sys/kernel/debug/fail*/stacktrace-depth:
  97
  98         specifies the maximum stacktrace depth walked during search
  99         for a caller within [require-start,require-end) OR
 100         [reject-start,reject-end).
 101
 102 - /sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem:
 103
 104         Format: { 'Y' | 'N' }
 105         default is 'N', setting it to 'Y' won't inject failures into
 106         highmem/user allocations.
 107
 108 - /sys/kernel/debug/failslab/ignore-gfp-wait:
 109 - /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait:
 110
 111         Format: { 'Y' | 'N' }
 112         default is 'N', setting it to 'Y' will inject failures
 113         only into non-sleep allocations (GFP_ATOMIC allocations).
 114
 115 - /sys/kernel/debug/fail_page_alloc/min-order:
 116
 117         specifies the minimum page allocation order to be injected
 118         failures.
 119
 120 - /sys/kernel/debug/fail_futex/ignore-private:
 121
 122         Format: { 'Y' | 'N' }
 123         default is 'N', setting it to 'Y' will disable failure injections
 124         when dealing with private (address space) futexes.
 125
 126 o Boot option
 127
 128 In order to inject faults while debugfs is not available (early boot time),
 129 use the boot option:
 130
 131         failslab=
 132         fail_page_alloc=
 133         fail_make_request=
 134         fail_futex=
 135         mmc_core.fail_request=<interval>,<probability>,<space>,<times>
 136
 137 o proc entries
 138
 139 - /proc/self/task/<current-tid>/fail-nth:
 140
 141         Write to this file of integer N makes N-th call in the current task fail
 142         (N is 0-based). Read from this file returns a single char 'Y' or 'N'
 143         that says if the fault setup with a previous write to this file was
 144         injected or not, and disables the fault if it 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.
 149
 150         This feature is intended for systematic testing of faults in a single
 151         system call. See an example below.
 152
 153 How to add new fault injection capability
 154 -----------------------------------------
 155
 156 o #include <linux/fault-inject.h>
 157
 158 o define the fault attributes
 159
 160   DECLARE_FAULT_INJECTION(name);
 161
 162   Please see the definition of struct fault_attr in fault-inject.h
 163   for details.
 164
 165 o provide a way to configure fault attributes
 166
 167 - boot option
 168
 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:
 171
 172         setup_fault_attr(attr, str);
 173
 174 - debugfs entries
 175
 176   failslab, fail_page_alloc, and fail_make_request use this way.
 177   Helper functions:
 178
 179         fault_create_debugfs_attr(name, parent, attr);
 180
 181 - module parameters
 182
 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.
 186
 187 o add a hook to insert failures
 188
 189   Upon should_fail() returning true, client code should inject a failure.
 190
 191         should_fail(attr, size);
 192
 193 Application Examples
 194 --------------------
 195
 196 o Inject slab allocation failures into module init/exit code
 197
 198 #!/bin/bash
 199
 200 FAILTYPE=failslab
 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
 208
 209 faulty_system()
 210 {
 211         bash -c "echo 1 > /proc/self/make-it-fail && exec $*"
 212 }
 213
 214 if [ $# -eq 0 ]
 215 then
 216         echo "Usage: $0 modulename [ modulename ... ]"
 217         exit 1
 218 fi
 219
 220 for m in $*
 221 do
 222         echo inserting $m...
 223         faulty_system modprobe $m
 224
 225         echo removing $m...
 226         faulty_system modprobe -r $m
 227 done
 228
 229 ------------------------------------------------------------------------------
 230
 231 o Inject page allocation failures only for a specific module
 232
 233 #!/bin/bash
 234
 235 FAILTYPE=fail_page_alloc
 236 module=$1
 237
 238 if [ -z $module ]
 239 then
 240         echo "Usage: $0 <modulename>"
 241         exit 1
 242 fi
 243
 244 modprobe $module
 245
 246 if [ ! -d /sys/module/$module/sections ]
 247 then
 248         echo Module $module is not loaded
 249         exit 1
 250 fi
 251
 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
 254
 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
 264
 265 trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
 266
 267 echo "Injecting errors into the module $module... (interrupt to stop)"
 268 sleep 1000000
 269
 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.
 276
 277 Examples:
 278
 279 Run a command "make -C tools/testing/selftests/ run_tests" with injecting slab
 280 allocation failure.
 281
 282         # ./tools/testing/fault-injection/failcmd.sh \
 283                 -- make -C tools/testing/selftests/ run_tests
 284
 285 Same as above except to specify 100 times failures at most instead of one time
 286 at most by default.
 287
 288         # ./tools/testing/fault-injection/failcmd.sh --times=100 \
 289                 -- make -C tools/testing/selftests/ run_tests
 290
 291 Same as above except to inject page allocation failure instead of slab
 292 allocation failure.
 293
 294         # env FAILCMD_TYPE=fail_page_alloc \
 295                 ./tools/testing/fault-injection/failcmd.sh --times=100 \
 296                 -- make -C tools/testing/selftests/ run_tests
 297
 298 Systematic faults using fail-nth
 299 ---------------------------------
 300
 301 The following code systematically faults 0-th, 1-st, 2-nd and so on
 302 capabilities in the socketpair() system call.
 303
 304 #include <sys/types.h>
 305 #include <sys/stat.h>
 306 #include <sys/socket.h>
 307 #include <sys/syscall.h>
 308 #include <fcntl.h>
 309 #include <unistd.h>
 310 #include <string.h>
 311 #include <stdlib.h>
 312 #include <stdio.h>
 313 #include <errno.h>
 314
 315 int main()
 316 {
 317         int i, err, res, fail_nth, fds[2];
 318         char buf[128];
 319
 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);
 323         for (i = 0;; i++) {
 324                 sprintf(buf, "%d", i);
 325                 write(fail_nth, buf, strlen(buf));
 326                 res = socketpair(AF_LOCAL, SOCK_STREAM, 0, fds);
 327                 err = errno;
 328                 read(fail_nth, buf, 1);
 329                 if (res == 0) {
 330                         close(fds[0]);
 331                         close(fds[1]);
 332                 }
 333                 printf("%d-th fault %c: res=%d/%d\n", i, buf[0], res, err);
 334                 if (buf[0] != 'Y')
 335                         break;
 336         }
 337         return 0;
 338 }
 339
 340 An example output:
 341
 342 0-th fault Y: res=-1/23
 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