Documentation/kdump/kdump.txt

   1 Documentation for kdump - the kexec-based crash dumping solution
   2 ================================================================
   3
   4 DESIGN
   5 ======
   6
   7 Kdump uses kexec to reboot to a second kernel whenever a dump needs to be taken.
   8 This second kernel is booted with very little memory. The first kernel reserves
   9 the section of memory that the second kernel uses. This ensures that on-going
  10 DMA from the first kernel does not corrupt the second kernel.
  11
  12 All the necessary information about Core image is encoded in ELF format and
  13 stored in reserved area of memory before crash. Physical address of start of
  14 ELF header is passed to new kernel through command line parameter elfcorehdr=.
  15
  16 On i386, the first 640 KB of physical memory is needed to boot, irrespective
  17 of where the kernel loads. Hence, this region is backed up by kexec just before
  18 rebooting into the new kernel.
  19
  20 In the second kernel, "old memory" can be accessed in two ways.
  21
  22 - The first one is through a /dev/oldmem device interface. A capture utility
  23   can read the device file and write out the memory in raw format. This is raw
  24   dump of memory and analysis/capture tool should be intelligent enough to
  25   determine where to look for the right information. ELF headers (elfcorehdr=)
  26   can become handy here.
  27
  28 - The second interface is through /proc/vmcore. This exports the dump as an ELF
  29   format file which can be written out using any file copy command
  30   (cp, scp, etc). Further, gdb can be used to perform limited debugging on
  31   the dump file. This method ensures methods ensure that there is correct
  32   ordering of the dump pages (corresponding to the first 640 KB that has been
  33   relocated).
  34
  35 SETUP
  36 =====
  37
  38 1) Download http://www.xmission.com/~ebiederm/files/kexec/kexec-tools-1.101.tar.gz
  39    and apply http://lse.sourceforge.net/kdump/patches/kexec-tools-1.101-kdump.patch
  40    and after that build the source.
  41
  42 2) Download and build the appropriate (2.6.13-rc1 onwards) vanilla kernel.
  43
  44    Two kernels need to be built in order to get this feature working.
  45
  46   A) First kernel:
  47    a) Enable "kexec system call" feature (in Processor type and features).
  48         CONFIG_KEXEC=y
  49    b) This kernel's physical load address should be the default value of
  50       0x100000 (0x100000, 1 MB) (in Processor type and features).
  51         CONFIG_PHYSICAL_START=0x100000
  52    c) Enable "sysfs file system support" (in Pseudo filesystems).
  53         CONFIG_SYSFS=y
  54    d) Boot into first kernel with the command line parameter "crashkernel=Y@X".
  55       Use appropriate values for X and Y. Y denotes how much memory to reserve
  56       for the second kernel, and X denotes at what physical address the reserved
  57       memory section starts. For example: "crashkernel=64M@16M".
  58
  59   B) Second kernel:
  60    a) Enable "kernel crash dumps" feature (in Processor type and features).
  61         CONFIG_CRASH_DUMP=y
  62    b) Specify a suitable value for "Physical address where the kernel is
  63       loaded" (in Processor type and features). Typically this value
  64       should be same as X (See option d) above, e.g., 16 MB or 0x1000000.
  65         CONFIG_PHYSICAL_START=0x1000000
  66    c) Enable "/proc/vmcore support" (Optional, in Pseudo filesystems).
  67         CONFIG_PROC_VMCORE=y
  68    d) Disable SMP support and build a UP kernel (Until it is fixed).
  69         CONFIG_SMP=n
  70    e) Enable "Local APIC support on uniprocessors".
  71         CONFIG_X86_UP_APIC=y
  72    f) Enable "IO-APIC support on uniprocessors"
  73         CONFIG_X86_UP_IOAPIC=y
  74
  75   Note:   i) Options a) and b) depend upon "Configure standard kernel features
  76              (for small systems)" (under General setup).
  77          ii) Option a) also depends on CONFIG_HIGHMEM (under Processor
  78                 type and features).
  79         iii) Both option a) and b) are under "Processor type and features".
  80
  81 3) Boot into the first kernel. You are now ready to try out kexec-based crash
  82    dumps.
  83
  84 4) Load the second kernel to be booted using:
  85
  86    kexec -p <second-kernel> --args-linux --elf32-core-headers
  87    --append="root=<root-dev> init 1 irqpoll"
  88
  89    Note: i) <second-kernel> has to be a vmlinux image. bzImage will not work,
  90             as of now.
  91         ii) By default ELF headers are stored in ELF64 format. Option
  92             --elf32-core-headers forces generation of ELF32 headers. gdb can
  93             not open ELF64 headers on 32 bit systems. So creating ELF32
  94             headers can come handy for users who have got non-PAE systems and
  95             hence have memory less than 4GB.
  96        iii) Specify "irqpoll" as command line parameter. This reduces driver
  97             initialization failures in second kernel due to shared interrupts.
  98
  99 5) System reboots into the second kernel when a panic occurs. A module can be
 100    written to force the panic or "ALT-SysRq-c" can be used initiate a crash
 101    dump for testing purposes.
 102
 103 6) Write out the dump file using
 104
 105    cp /proc/vmcore <dump-file>
 106
 107    Dump memory can also be accessed as a /dev/oldmem device for a linear/raw
 108    view.  To create the device, type:
 109
 110    mknod /dev/oldmem c 1 12
 111
 112    Use "dd" with suitable options for count, bs and skip to access specific
 113    portions of the dump.
 114
 115    Entire memory:  dd if=/dev/oldmem of=oldmem.001
 116
 117 ANALYSIS
 118 ========
 119
 120 Limited analysis can be done using gdb on the dump file copied out of
 121 /proc/vmcore. Use vmlinux built with -g and run
 122
 123   gdb vmlinux <dump-file>
 124
 125 Stack trace for the task on processor 0, register display, memory display
 126 work fine.
 127
 128 Note: gdb cannot analyse core files generated in ELF64 format for i386.
 129
 130 TODO
 131 ====
 132
 133 1) Provide a kernel pages filtering mechanism so that core file size is not
 134    insane on systems having huge memory banks.
 135 2) Modify "crash" tool to make it recognize this dump.
 136
 137 CONTACT
 138 =======
 139
 140 Vivek Goyal (vgoyal@in.ibm.com)
 141 Maneesh Soni (maneesh@in.ibm.com)