Documentation/fault-injection/provoke-crashes.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ============================================================
   4 Provoking crashes with Linux Kernel Dump Test Module (LKDTM)
   5 ============================================================
   6
   7 The lkdtm module provides an interface to disrupt (and usually crash)
   8 the kernel at predefined code locations to evaluate the reliability of
   9 the kernel's exception handling and to test crash dumps obtained using
  10 different dumping solutions. The module uses KPROBEs to instrument the
  11 trigger location, but can also trigger the kernel directly without KPROBE
  12 support via debugfs.
  13
  14 You can select the location of the trigger ("crash point name") and the
  15 type of action ("crash point type") either through module arguments when
  16 inserting the module, or through the debugfs interface.
  17
  18 Usage::
  19
  20         insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
  21                         [cpoint_count={>0}]
  22
  23 recur_count
  24         Recursion level for the stack overflow test. By default this is
  25         dynamically calculated based on kernel configuration, with the
  26         goal of being just large enough to exhaust the kernel stack. The
  27         value can be seen at `/sys/module/lkdtm/parameters/recur_count`.
  28
  29 cpoint_name
  30         Where in the kernel to trigger the action. It can be
  31         one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
  32         FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_QUEUE_RQ, or DIRECT.
  33
  34 cpoint_type
  35         Indicates the action to be taken on hitting the crash point.
  36         These are numerous, and best queried directly from debugfs. Some
  37         of the common ones are PANIC, BUG, EXCEPTION, LOOP, and OVERFLOW.
  38         See the contents of `/sys/kernel/debug/provoke-crash/DIRECT` for
  39         a complete list.
  40
  41 cpoint_count
  42         Indicates the number of times the crash point is to be hit
  43         before triggering the action. The default is 10 (except for
  44         DIRECT, which always fires immediately).
  45
  46 You can also induce failures by mounting debugfs and writing the type to
  47 <debugfs>/provoke-crash/<crashpoint>. E.g.::
  48
  49   mount -t debugfs debugfs /sys/kernel/debug
  50   echo EXCEPTION > /sys/kernel/debug/provoke-crash/INT_HARDWARE_ENTRY
  51
  52 The special file `DIRECT` will induce the action directly without KPROBE
  53 instrumentation. This mode is the only one available when the module is
  54 built for a kernel without KPROBEs support::
  55
  56   # Instead of having a BUG kill your shell, have it kill "cat":
  57   cat <(echo WRITE_RO) >/sys/kernel/debug/provoke-crash/DIRECT