memory image to a dump file on the local disk, or across the network to
a remote system.
-Kdump and kexec are currently supported on the x86, x86_64, and ppc64
+Kdump and kexec are currently supported on the x86, x86_64, ppc64 and ia64
architectures.
When the system kernel boots, it reserves a small section of memory for
regardless of where the kernel loads. Therefore, kexec backs up this
region just before rebooting into the dump-capture kernel.
+Similarly on PPC64 machines first 32KB of physical memory is needed for
+booting regardless of where the kernel is loaded and to support 64K page
+size kexec backs up the first 64KB memory.
+
All of the necessary information about the system kernel's core image is
encoded in the ELF format, and stored in a reserved area of memory
before a crash. The physical address of the start of the ELF header is
Setup and Installation
======================
-Install kexec-tools and the Kdump patch
----------------------------------------
+Install kexec-tools
+-------------------
1) Login as the root user.
2) Download the kexec-tools user-space package from the following URL:
- http://www.xmission.com/~ebiederm/files/kexec/kexec-tools-1.101.tar.gz
-
-3) Unpack the tarball with the tar command, as follows:
+http://www.kernel.org/pub/linux/kernel/people/horms/kexec-tools/kexec-tools-testing.tar.gz
- tar xvpzf kexec-tools-1.101.tar.gz
+This is a symlink to the latest version, which at the time of writing is
+20061214, the only release of kexec-tools-testing so far. As other versions
+are made released, the older onese will remain available at
+http://www.kernel.org/pub/linux/kernel/people/horms/kexec-tools/
-4) Download the latest consolidated Kdump patch from the following URL:
+Note: Latest kexec-tools-testing git tree is available at
- http://lse.sourceforge.net/kdump/
+git://git.kernel.org/pub/scm/linux/kernel/git/horms/kexec-tools-testing.git
+or
+http://www.kernel.org/git/?p=linux/kernel/git/horms/kexec-tools-testing.git;a=summary
- (This location is being used until all the user-space Kdump patches
- are integrated with the kexec-tools package.)
-
-5) Change to the kexec-tools-1.101 directory, as follows:
+3) Unpack the tarball with the tar command, as follows:
- cd kexec-tools-1.101
+ tar xvpzf kexec-tools-testing.tar.gz
-6) Apply the consolidated patch to the kexec-tools-1.101 source tree
- with the patch command, as follows. (Modify the path to the downloaded
- patch as necessary.)
+4) Change to the kexec-tools directory, as follows:
- patch -p1 < /path-to-kdump-patch/kexec-tools-1.101-kdump.patch
+ cd kexec-tools-testing-VERSION
-7) Configure the package, as follows:
+5) Configure the package, as follows:
./configure
-8) Compile the package, as follows:
+6) Compile the package, as follows:
make
-9) Install the package, as follows:
+7) Install the package, as follows:
make install
-Download and build the system and dump-capture kernels
-------------------------------------------------------
+Build the system and dump-capture kernels
+-----------------------------------------
+There are two possible methods of using Kdump.
-Download the mainline (vanilla) kernel source code (2.6.13-rc1 or newer)
-from http://www.kernel.org. Two kernels must be built: a system kernel
-and a dump-capture kernel. Use the following steps to configure these
-kernels with the necessary kexec and Kdump features:
+1) Build a separate custom dump-capture kernel for capturing the
+ kernel core dump.
-System kernel
--------------
+2) Or use the system kernel binary itself as dump-capture kernel and there is
+ no need to build a separate dump-capture kernel. This is possible
+ only with the architecutres which support a relocatable kernel. As
+ of today i386 and ia64 architectures support relocatable kernel.
+
+Building a relocatable kernel is advantageous from the point of view that
+one does not have to build a second kernel for capturing the dump. But
+at the same time one might want to build a custom dump capture kernel
+suitable to his needs.
+
+Following are the configuration setting required for system and
+dump-capture kernels for enabling kdump support.
+
+System kernel config options
+----------------------------
1) Enable "kexec system call" in "Processor type and features."
analysis tools require a vmlinux with debug symbols in order to read
and analyze a dump file.
-4) Make and install the kernel and its modules. Update the boot loader
- (such as grub, yaboot, or lilo) configuration files as necessary.
+Dump-capture kernel config options (Arch Independent)
+-----------------------------------------------------
-5) Boot the system kernel with the boot parameter "crashkernel=Y@X",
- where Y specifies how much memory to reserve for the dump-capture kernel
- and X specifies the beginning of this reserved memory. For example,
- "crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory
- starting at physical address 0x01000000 for the dump-capture kernel.
-
- On x86 and x86_64, use "crashkernel=64M@16M".
-
- On ppc64, use "crashkernel=128M@32M".
+1) Enable "kernel crash dumps" support under "Processor type and
+ features":
+ CONFIG_CRASH_DUMP=y
-The dump-capture kernel
------------------------
+2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems".
-1) Under "General setup," append "-kdump" to the current string in
- "Local version."
+ CONFIG_PROC_VMCORE=y
+ (CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.)
-2) On x86, enable high memory support under "Processor type and
+Dump-capture kernel config options (Arch Dependent, i386)
+--------------------------------------------------------
+1) On x86, enable high memory support under "Processor type and
features":
CONFIG_HIGHMEM64G=y
or
CONFIG_HIGHMEM4G
-3) On x86 and x86_64, disable symmetric multi-processing support
+2) On x86 and x86_64, disable symmetric multi-processing support
under "Processor type and features":
CONFIG_SMP=n
+
(If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line
when loading the dump-capture kernel, see section "Load the Dump-capture
Kernel".)
-4) On ppc64, disable NUMA support and enable EMBEDDED support:
+3) If one wants to build and use a relocatable kernel,
+ Enable "Build a relocatable kernel" support under "Processor type and
+ features"
- CONFIG_NUMA=n
- CONFIG_EMBEDDED=y
- CONFIG_EEH=N for the dump-capture kernel
+ CONFIG_RELOCATABLE=y
-5) Enable "kernel crash dumps" support under "Processor type and
- features":
+4) Use a suitable value for "Physical address where the kernel is
+ loaded" (under "Processor type and features"). This only appears when
+ "kernel crash dumps" is enabled. A suitable value depends upon
+ whether kernel is relocatable or not.
+
+ If you are using a relocatable kernel use CONFIG_PHYSICAL_START=0x100000
+ This will compile the kernel for physical address 1MB, but given the fact
+ kernel is relocatable, it can be run from any physical address hence
+ kexec boot loader will load it in memory region reserved for dump-capture
+ kernel.
+
+ Otherwise it should be the start of memory region reserved for
+ second kernel using boot parameter "crashkernel=Y@X". Here X is
+ start of memory region reserved for dump-capture kernel.
+ Generally X is 16MB (0x1000000). So you can set
+ CONFIG_PHYSICAL_START=0x1000000
+
+5) Make and install the kernel and its modules. DO NOT add this kernel
+ to the boot loader configuration files.
- CONFIG_CRASH_DUMP=y
+Dump-capture kernel config options (Arch Dependent, x86_64)
+----------------------------------------------------------
+1) On x86 and x86_64, disable symmetric multi-processing support
+ under "Processor type and features":
-6) Use a suitable value for "Physical address where the kernel is
+ CONFIG_SMP=n
+
+ (If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line
+ when loading the dump-capture kernel, see section "Load the Dump-capture
+ Kernel".)
+
+2) Use a suitable value for "Physical address where the kernel is
loaded" (under "Processor type and features"). This only appears when
"kernel crash dumps" is enabled. By default this value is 0x1000000
(16MB). It should be the same as X in the "crashkernel=Y@X" boot
- parameter discussed above.
+ parameter.
- On x86 and x86_64, use "CONFIG_PHYSICAL_START=0x1000000".
+ For x86_64, normally "CONFIG_PHYSICAL_START=0x1000000".
- On ppc64 the value is automatically set at 32MB when
- CONFIG_CRASH_DUMP is set.
+3) Make and install the kernel and its modules. DO NOT add this kernel
+ to the boot loader configuration files.
-6) Optionally enable "/proc/vmcore support" under "Filesystems" ->
- "Pseudo filesystems".
+Dump-capture kernel config options (Arch Dependent, ppc64)
+----------------------------------------------------------
- CONFIG_PROC_VMCORE=y
- (CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.)
-
-7) Make and install the kernel and its modules. DO NOT add this kernel
+* Make and install the kernel and its modules. DO NOT add this kernel
to the boot loader configuration files.
+Dump-capture kernel config options (Arch Dependent, ia64)
+----------------------------------------------------------
+
+- No specific options are required to create a dump-capture kernel
+ for ia64, other than those specified in the arch idependent section
+ above. This means that it is possible to use the system kernel
+ as a dump-capture kernel if desired.
+
+ The crashkernel region can be automatically placed by the system
+ kernel at run time. This is done by specifying the base address as 0,
+ or omitting it all together.
+
+ crashkernel=256M@0
+ or
+ crashkernel=256M
+
+ If the start address is specified, note that the start address of the
+ kernel will be aligned to 64Mb, so if the start address is not then
+ any space below the alignment point will be wasted.
+
+
+Boot into System Kernel
+=======================
+
+1) Update the boot loader (such as grub, yaboot, or lilo) configuration
+ files as necessary.
+
+2) Boot the system kernel with the boot parameter "crashkernel=Y@X",
+ where Y specifies how much memory to reserve for the dump-capture kernel
+ and X specifies the beginning of this reserved memory. For example,
+ "crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory
+ starting at physical address 0x01000000 (16MB) for the dump-capture kernel.
+
+ On x86 and x86_64, use "crashkernel=64M@16M".
+
+ On ppc64, use "crashkernel=128M@32M".
+
+ On ia64, 256M@256M is a generous value that typically works.
+ The region may be automatically placed on ia64, see the
+ dump-capture kernel config option notes above.
Load the Dump-capture Kernel
============================
-After booting to the system kernel, load the dump-capture kernel using
-the following command:
+After booting to the system kernel, dump-capture kernel needs to be
+loaded.
+
+Based on the architecture and type of image (relocatable or not), one
+can choose to load the uncompressed vmlinux or compressed bzImage/vmlinuz
+of dump-capture kernel. Following is the summary.
+
+For i386:
+ - Use vmlinux if kernel is not relocatable.
+ - Use bzImage/vmlinuz if kernel is relocatable.
+For x86_64:
+ - Use vmlinux
+For ppc64:
+ - Use vmlinux
+For ia64:
+ - Use vmlinux or vmlinuz.gz
+
+
+If you are using a uncompressed vmlinux image then use following command
+to load dump-capture kernel.
- kexec -p <dump-capture-kernel> \
+ kexec -p <dump-capture-kernel-vmlinux-image> \
--initrd=<initrd-for-dump-capture-kernel> --args-linux \
- --append="root=<root-dev> init 1 irqpoll"
+ --append="root=<root-dev> <arch-specific-options>"
+If you are using a compressed bzImage/vmlinuz, then use following command
+to load dump-capture kernel.
-Notes on loading the dump-capture kernel:
+ kexec -p <dump-capture-kernel-bzImage> \
+ --initrd=<initrd-for-dump-capture-kernel> \
+ --append="root=<root-dev> <arch-specific-options>"
+
+Please note, that --args-linux does not need to be specified for ia64.
+It is planned to make this a no-op on that architecture, but for now
+it should be omitted
+
+Following are the arch specific command line options to be used while
+loading dump-capture kernel.
+
+For i386, x86_64 and ia64:
+ "1 irqpoll maxcpus=1"
-* <dump-capture-kernel> must be a vmlinux image (that is, an
- uncompressed ELF image). bzImage does not work at this time.
+For ppc64:
+ "1 maxcpus=1 noirqdistrib"
+
+
+Notes on loading the dump-capture kernel:
* By default, the ELF headers are stored in ELF64 format to support
systems with more than 4GB memory. The --elf32-core-headers option can
* You must specify <root-dev> in the format corresponding to the root
device name in the output of mount command.
-* "init 1" boots the dump-capture kernel into single-user mode without
- networking. If you want networking, use "init 3."
+* Boot parameter "1" boots the dump-capture kernel into single-user
+ mode without networking. If you want networking, use "3".
+* We generally don' have to bring up a SMP kernel just to capture the
+ dump. Hence generally it is useful either to build a UP dump-capture
+ kernel or specify maxcpus=1 option while loading dump-capture kernel.
Kernel Panic
============
is called inside interrupt context or die() is called and panic_on_oops is set,
the system will boot into the dump-capture kernel.
-On powererpc systems when a soft-reset is generated, die() is called by all cpus and the system will boot into the dump-capture kernel.
+On powererpc systems when a soft-reset is generated, die() is called by all cpus
+and the system will boot into the dump-capture kernel.
For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
-"echo c > /proc/sysrq-trigger or write a module to force the panic.
+"echo c > /proc/sysrq-trigger" or write a module to force the panic.
Write Out the Dump File
=======================
To Do
=====
-1) Provide a kernel pages filtering mechanism, so core file size is not
- extreme on systems with huge memory banks.
-
-2) Relocatable kernel can help in maintaining multiple kernels for
- crash_dump, and the same kernel as the system kernel can be used to
- capture the dump.
+1) Provide relocatable kernels for all architectures to help in maintaining
+ multiple kernels for crash_dump, and the same kernel as the system kernel
+ can be used to capture the dump.
Contact
git.openpandora.org / pandora-kernel.git / blobdiff