Documentation/fault-injection/notifier-error-inject.txt

   1 Notifier error injection
   2 ========================
   3
   4 Notifier error injection provides the ability to inject artificial errors to
   5 specified notifier chain callbacks. It is useful to test the error handling of
   6 notifier call chain failures which is rarely executed.  There are kernel
   7 modules that can be used to test the following notifiers.
   8
   9  * CPU notifier
  10  * PM notifier
  11  * Memory hotplug notifier
  12  * powerpc pSeries reconfig notifier
  13  * Netdevice notifier
  14
  15 CPU notifier error injection module
  16 -----------------------------------
  17 This feature can be used to test the error handling of the CPU notifiers by
  18 injecting artificial errors to CPU notifier chain callbacks.
  19
  20 If the notifier call chain should be failed with some events notified, write
  21 the error code to debugfs interface
  22 /sys/kernel/debug/notifier-error-inject/cpu/actions/<notifier event>/error
  23
  24 Possible CPU notifier events to be failed are:
  25
  26  * CPU_UP_PREPARE
  27  * CPU_UP_PREPARE_FROZEN
  28  * CPU_DOWN_PREPARE
  29  * CPU_DOWN_PREPARE_FROZEN
  30
  31 Example1: Inject CPU offline error (-1 == -EPERM)
  32
  33         # cd /sys/kernel/debug/notifier-error-inject/cpu
  34         # echo -1 > actions/CPU_DOWN_PREPARE/error
  35         # echo 0 > /sys/devices/system/cpu/cpu1/online
  36         bash: echo: write error: Operation not permitted
  37
  38 Example2: inject CPU online error (-2 == -ENOENT)
  39
  40         # echo -2 > actions/CPU_UP_PREPARE/error
  41         # echo 1 > /sys/devices/system/cpu/cpu1/online
  42         bash: echo: write error: No such file or directory
  43
  44 PM notifier error injection module
  45 ----------------------------------
  46 This feature is controlled through debugfs interface
  47 /sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
  48
  49 Possible PM notifier events to be failed are:
  50
  51  * PM_HIBERNATION_PREPARE
  52  * PM_SUSPEND_PREPARE
  53  * PM_RESTORE_PREPARE
  54
  55 Example: Inject PM suspend error (-12 = -ENOMEM)
  56
  57         # cd /sys/kernel/debug/notifier-error-inject/pm/
  58         # echo -12 > actions/PM_SUSPEND_PREPARE/error
  59         # echo mem > /sys/power/state
  60         bash: echo: write error: Cannot allocate memory
  61
  62 Memory hotplug notifier error injection module
  63 ----------------------------------------------
  64 This feature is controlled through debugfs interface
  65 /sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
  66
  67 Possible memory notifier events to be failed are:
  68
  69  * MEM_GOING_ONLINE
  70  * MEM_GOING_OFFLINE
  71
  72 Example: Inject memory hotplug offline error (-12 == -ENOMEM)
  73
  74         # cd /sys/kernel/debug/notifier-error-inject/memory
  75         # echo -12 > actions/MEM_GOING_OFFLINE/error
  76         # echo offline > /sys/devices/system/memory/memoryXXX/state
  77         bash: echo: write error: Cannot allocate memory
  78
  79 powerpc pSeries reconfig notifier error injection module
  80 --------------------------------------------------------
  81 This feature is controlled through debugfs interface
  82 /sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
  83
  84 Possible pSeries reconfig notifier events to be failed are:
  85
  86  * PSERIES_RECONFIG_ADD
  87  * PSERIES_RECONFIG_REMOVE
  88  * PSERIES_DRCONF_MEM_ADD
  89  * PSERIES_DRCONF_MEM_REMOVE
  90
  91 Netdevice notifier error injection module
  92 ----------------------------------------------
  93 This feature is controlled through debugfs interface
  94 /sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
  95
  96 Netdevice notifier events which can be failed are:
  97
  98  * NETDEV_REGISTER
  99  * NETDEV_CHANGEMTU
 100  * NETDEV_CHANGENAME
 101  * NETDEV_PRE_UP
 102  * NETDEV_PRE_TYPE_CHANGE
 103  * NETDEV_POST_INIT
 104  * NETDEV_PRECHANGEMTU
 105  * NETDEV_PRECHANGEUPPER
 106  * NETDEV_CHANGEUPPER
 107
 108 Example: Inject netdevice mtu change error (-22 == -EINVAL)
 109
 110         # cd /sys/kernel/debug/notifier-error-inject/netdev
 111         # echo -22 > actions/NETDEV_CHANGEMTU/error
 112         # ip link set eth0 mtu 1024
 113         RTNETLINK answers: Invalid argument
 114
 115 For more usage examples
 116 -----------------------
 117 There are tools/testing/selftests using the notifier error injection features
 118 for CPU and memory notifiers.
 119
 120  * tools/testing/selftests/cpu-hotplug/on-off-test.sh
 121  * tools/testing/selftests/memory-hotplug/on-off-test.sh
 122
 123 These scripts first do simple online and offline tests and then do fault
 124 injection tests if notifier error injection module is available.