Documentation/kdump.txt

   1 Documentation for kdump - the kexec based crash dumping solution
   2 ================================================================
   3
   4 DESIGN
   5 ======
   6
   7 We use kexec to reboot to a second kernel whenever a dump needs to be taken.
   8 This second kernel is booted with with very little memory (configurable
   9 at compile time). The first kernel reserves the section of memory that the
  10 second kernel uses. This ensures that on-going DMA from the first kernel
  11 does not corrupt the second kernel. The first 640k of physical memory is
  12 needed irrespective of where the kernel loads at. Hence, this region is
  13 backed up before reboot.
  14
  15 In the second kernel, "old memory" can be accessed in two ways. The
  16 first one is through a device interface. We can create a /dev/oldmem or
  17 whatever and write out the memory in raw format. The second interface is
  18 through /proc/vmcore. This exports the dump as an ELF format file which
  19 can be written out using any file copy command (cp, scp, etc). Further, gdb
  20 can be used to perform some minimal debugging on the dump file. Both these
  21 methods ensure that there is correct ordering of the dump pages (corresponding
  22 to the first 640k that has been relocated).
  23
  24 SETUP
  25 =====
  26
  27 1) Obtain the appropriate -mm tree patch and apply it on to the vanilla
  28    kernel tree.
  29
  30 2) Two kernels need to be built in order to get this feature working.
  31
  32    For the first kernel, choose the default values for the following options.
  33
  34    a) Physical address where the kernel is loaded
  35    b) kexec system call
  36    c) kernel crash dumps
  37
  38    All the options are under "Processor type and features"
  39
  40    For the second kernel, change (a) to 16MB. If you want to choose another
  41    value here, ensure "location from where the crash dumping kernel will boot
  42    (MB)" under (c) reflects the same value.
  43
  44    Also ensure you have CONFIG_HIGHMEM on.
  45
  46 3) Boot into the first kernel. You are now ready to try out kexec based crash
  47    dumps.
  48
  49 4) Load the second kernel to be booted using
  50
  51    kexec -p <second-kernel> --args-linux --append="root=<root-dev> dump
  52    init 1 memmap=exactmap memmap=640k@0 memmap=32M@16M"
  53
  54    Note that <second-kernel> has to be a vmlinux image. bzImage will not
  55    work, as of now.
  56
  57 5) Enable kexec based dumping by
  58
  59    echo 1 > /proc/kexec-dump
  60
  61    If this is not set, the system will not do a kexec reboot in the event
  62    of a panic.
  63
  64 6) System reboots into the second kernel when a panic occurs.
  65    You could write a module to call panic, for testing purposes.
  66
  67 7) Write out the dump file using
  68
  69    cp /proc/vmcore <dump-file>
  70
  71 You can also access the dump as a device for a linear/raw view. To do this,
  72 you will need the kd-oldmem-<version>.patch built into the kernel. To create
  73 the device, type
  74
  75   mknod /dev/oldmem c 1 12
  76
  77 Use "dd" with suitable options for count, bs and skip to access specific
  78 portions of the dump.
  79
  80 ANALYSIS
  81 ========
  82
  83 You can run gdb on the dump file copied out of /proc/vmcore. Use vmlinux built
  84 with -g and run
  85
  86   gdb vmlinux <dump-file>
  87
  88 Stack trace for the task on processor 0, register display, memory display
  89 work fine.
  90
  91 TODO
  92 ====
  93
  94 1) Provide a kernel-pages only view for the dump. This could possibly turn up
  95    as /proc/vmcore-kern.
  96 2) Provide register contents of all processors (similar to what multi-threaded
  97    core dumps does).
  98 3) Modify "crash" to make it recognize this dump.
  99 4) Make the i386 kernel boot from any location so we can run the second kernel
 100    from the reserved location instead of the current approach.
 101
 102 CONTACT
 103 =======
 104
 105 Hariprasad Nellitheertha - hari at in dot ibm dot com