1Notifier error injection
  2========================
  3
  4Notifier error injection provides the ability to inject artificial errors to
  5specified notifier chain callbacks. It is useful to test the error handling of
  6notifier call chain failures which is rarely executed.  There are kernel
  7modules 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
 15CPU notifier error injection module
 16-----------------------------------
 17This feature can be used to test the error handling of the CPU notifiers by
 18injecting artificial errors to CPU notifier chain callbacks.
 19
 20If the notifier call chain should be failed with some events notified, write
 21the error code to debugfs interface
 22/sys/kernel/debug/notifier-error-inject/cpu/actions/<notifier event>/error
 23
 24Possible 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
 31Example1: 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
 38Example2: 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
 44PM notifier error injection module
 45----------------------------------
 46This feature is controlled through debugfs interface
 47/sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
 48
 49Possible PM notifier events to be failed are:
 50
 51 * PM_HIBERNATION_PREPARE
 52 * PM_SUSPEND_PREPARE
 53 * PM_RESTORE_PREPARE
 54
 55Example: 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
 62Memory hotplug notifier error injection module
 63----------------------------------------------
 64This feature is controlled through debugfs interface
 65/sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
 66
 67Possible memory notifier events to be failed are:
 68
 69 * MEM_GOING_ONLINE
 70 * MEM_GOING_OFFLINE
 71
 72Example: 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
 79powerpc pSeries reconfig notifier error injection module
 80--------------------------------------------------------
 81This feature is controlled through debugfs interface
 82/sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
 83
 84Possible 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
 91Netdevice notifier error injection module
 92----------------------------------------------
 93This feature is controlled through debugfs interface
 94/sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
 95
 96Netdevice 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
108Example: 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
115For more usage examples
116-----------------------
117There are tools/testing/selftests using the notifier error injection features
118for 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
123These scripts first do simple online and offline tests and then do fault
124injection tests if notifier error injection module is available.