summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKees Cook <keescook@chromium.org>2020-10-16 01:45:59 +0300
committerJonathan Corbet <corbet@lwn.net>2020-10-22 00:10:30 +0300
commitac8bf0de6ad7fa399d016d6dfc4b9c2f17625a8b (patch)
tree63b350d85490572ec7732eb657553fecd682d92f
parent27def953b63b43508021f31560b7d169c5f77857 (diff)
downloadlinux-ac8bf0de6ad7fa399d016d6dfc4b9c2f17625a8b.tar.xz
docs: lkdtm: Modernize and improve details
The details on using LKDTM were overly obscure. Modernize the details and expand examples to better illustrate how to use the interfaces. Additionally add missing SPDX header. Signed-off-by: Kees Cook <keescook@chromium.org> Link: https://lore.kernel.org/r/20201015224559.2137489-1-keescook@chromium.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
-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