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
14CPU notifier error injection module
15-----------------------------------
16This feature can be used to test the error handling of the CPU notifiers by
17injecting artificial errors to CPU notifier chain callbacks.
18
19If the notifier call chain should be failed with some events notified, write
20the error code to debugfs interface
21/sys/kernel/debug/notifier-error-inject/cpu/actions/<notifier event>/error
22
23Possible CPU notifier events to be failed are:
24
25 * CPU_UP_PREPARE
26 * CPU_UP_PREPARE_FROZEN
27 * CPU_DOWN_PREPARE
28 * CPU_DOWN_PREPARE_FROZEN
29
30Example1: Inject CPU offline error (-1 == -EPERM)
31
32	# cd /sys/kernel/debug/notifier-error-inject/cpu
33	# echo -1 > actions/CPU_DOWN_PREPARE/error
34	# echo 0 > /sys/devices/system/cpu/cpu1/online
35	bash: echo: write error: Operation not permitted
36
37Example2: inject CPU online error (-2 == -ENOENT)
38
39	# echo -2 > actions/CPU_UP_PREPARE/error
40	# echo 1 > /sys/devices/system/cpu/cpu1/online
41	bash: echo: write error: No such file or directory
42
43PM notifier error injection module
44----------------------------------
45This feature is controlled through debugfs interface
46/sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
47
48Possible PM notifier events to be failed are:
49
50 * PM_HIBERNATION_PREPARE
51 * PM_SUSPEND_PREPARE
52 * PM_RESTORE_PREPARE
53
54Example: Inject PM suspend error (-12 = -ENOMEM)
55
56	# cd /sys/kernel/debug/notifier-error-inject/pm/
57	# echo -12 > actions/PM_SUSPEND_PREPARE/error
58	# echo mem > /sys/power/state
59	bash: echo: write error: Cannot allocate memory
60
61Memory hotplug notifier error injection module
62----------------------------------------------
63This feature is controlled through debugfs interface
64/sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
65
66Possible memory notifier events to be failed are:
67
68 * MEM_GOING_ONLINE
69 * MEM_GOING_OFFLINE
70
71Example: Inject memory hotplug offline error (-12 == -ENOMEM)
72
73	# cd /sys/kernel/debug/notifier-error-inject/memory
74	# echo -12 > actions/MEM_GOING_OFFLINE/error
75	# echo offline > /sys/devices/system/memory/memoryXXX/state
76	bash: echo: write error: Cannot allocate memory
77
78powerpc pSeries reconfig notifier error injection module
79--------------------------------------------------------
80This feature is controlled through debugfs interface
81/sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
82
83Possible pSeries reconfig notifier events to be failed are:
84
85 * PSERIES_RECONFIG_ADD
86 * PSERIES_RECONFIG_REMOVE
87 * PSERIES_DRCONF_MEM_ADD
88 * PSERIES_DRCONF_MEM_REMOVE
89
90For more usage examples
91-----------------------
92There are tools/testing/selftests using the notifier error injection features
93for CPU and memory notifiers.
94
95 * tools/testing/selftests/cpu-hotplug/on-off-test.sh
96 * tools/testing/selftests/memory-hotplug/on-off-test.sh
97
98These scripts first do simple online and offline tests and then do fault
99injection tests if notifier error injection module is available.
100