summaryrefslogtreecommitdiff
path: root/Documentation/fault-injection
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2020-10-23 17:13:53 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2020-10-23 17:13:53 -0700
commitc80e42a4963b3f593d53fb8f565e5bbca61a6531 (patch)
tree63327ed70e63459b6f9b5899dc14c5b35ad54823 /Documentation/fault-injection
parenta5e5c274c920f693d9c1ab65440d8e53a4530aca (diff)
parent62af696471e58bdfcf416fd56f032a60853c2bae (diff)
Merge tag 'docs-5.10-2' of git://git.lwn.net/linux
Pull documentation fixes from Jonathan Corbet: "A handful of late-arriving documentation fixes" * tag 'docs-5.10-2' of git://git.lwn.net/linux: docs: Add two missing entries in vm sysctl index docs/vm: trivial fixes to several spelling mistakes docs: submitting-patches: describe preserving review/test tags Documentation: Chinese translation of Documentation/arm64/hugetlbpage.rst Documentation: x86: fix a missing word in x86_64/mm.rst. docs: driver-api: remove a duplicated index entry docs: lkdtm: Modernize and improve details docs: deprecated.rst: Expand str*cpy() replacement notes docs/cpu-load: format the example code.
Diffstat (limited to 'Documentation/fault-injection')
-rw-r--r--Documentation/fault-injection/provoke-crashes.rst56
1 files changed, 33 insertions, 23 deletions
diff --git a/Documentation/fault-injection/provoke-crashes.rst b/Documentation/fault-injection/provoke-crashes.rst
index 9279a3e12278..a20ba5d93932 100644
--- a/Documentation/fault-injection/provoke-crashes.rst
+++ b/Documentation/fault-injection/provoke-crashes.rst
@@ -1,16 +1,19 @@
-===============
-Provoke crashes
-===============
+.. SPDX-License-Identifier: GPL-2.0
-The lkdtm module provides an interface to crash or injure the kernel at
-predefined crashpoints to evaluate the reliability of crash dumps obtained
-using different dumping solutions. The module uses KPROBEs to instrument
-crashing points, but can also crash the kernel directly without KRPOBE
-support.
+============================================================
+Provoking crashes with Linux Kernel Dump Test Module (LKDTM)
+============================================================
+The lkdtm module provides an interface to disrupt (and usually crash)
+the kernel at predefined code locations to evaluate the reliability of
+the kernel's exception handling and to test crash dumps obtained using
+different dumping solutions. The module uses KPROBEs to instrument the
+trigger location, but can also trigger the kernel directly without KPROBE
+support via debugfs.
-You can provide the way either through module arguments when inserting
-the module, or through a debugfs interface.
+You can select the location of the trigger ("crash point name") and the
+type of action ("crash point type") either through module arguments when
+inserting the module, or through the debugfs interface.
Usage::
@@ -18,31 +21,38 @@ Usage::
[cpoint_count={>0}]
recur_count
- Recursion level for the stack overflow test. Default is 10.
+ Recursion level for the stack overflow test. By default this is
+ dynamically calculated based on kernel configuration, with the
+ goal of being just large enough to exhaust the kernel stack. The
+ value can be seen at `/sys/module/lkdtm/parameters/recur_count`.
cpoint_name
- Crash point where the kernel is to be crashed. It can be
+ Where in the kernel to trigger the action. It can be
one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
- IDE_CORE_CP, DIRECT
+ IDE_CORE_CP, or DIRECT
cpoint_type
Indicates the action to be taken on hitting the crash point.
- It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
- CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
- WRITE_AFTER_FREE,
+ These are numerous, and best queried directly from debugfs. Some
+ of the common ones are PANIC, BUG, EXCEPTION, LOOP, and OVERFLOW.
+ See the contents of `/sys/kernel/debug/provoke-crash/DIRECT` for
+ a complete list.
cpoint_count
Indicates the number of times the crash point is to be hit
- to trigger an action. The default is 10.
+ before triggering the action. The default is 10 (except for
+ DIRECT, which always fires immediately).
You can also induce failures by mounting debugfs and writing the type to
-<mountpoint>/provoke-crash/<crashpoint>. E.g.::
+<debugfs>/provoke-crash/<crashpoint>. E.g.::
- mount -t debugfs debugfs /mnt
- echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY
+ mount -t debugfs debugfs /sys/kernel/debug
+ echo EXCEPTION > /sys/kernel/debug/provoke-crash/INT_HARDWARE_ENTRY
+The special file `DIRECT` will induce the action directly without KPROBE
+instrumentation. This mode is the only one available when the module is
+built for a kernel without KPROBEs support::
-A special file is `DIRECT` which will induce the crash directly without
-KPROBE instrumentation. This mode is the only one available when the module
-is built on a kernel without KPROBEs support.
+ # Instead of having a BUG kill your shell, have it kill "cat":
+ cat <(echo WRITE_RO) >/sys/kernel/debug/provoke-crash/DIRECT