Copyright 2000 Silicon Graphics, Inc. All rights reserved.

README for LKCD

This document covers the following topics:

    - Overview of the Linux Kernel Crash Dump (LKCD) Project
    - Overview of LKCD Operation
    - Crash Dump Configuration Options
    - Configuring Your System for LKCD


Overview of the Linux Kernel Crash Dump (LKCD) Project
------------------------------------------------------

The primary objective of the Linux Kernel Crash Dump (LKCD) project is
to provide a kernel crash dump facility for the Linux kernel and to
provide Linux crash analysis tools that help determine the cause of a
system crash. LKCD consists of two components:

o Additions and changes to Linux kernel source necessary for 
  implementing system crash dump capabilities into the Linux kernel.

o Facilities for integrating system crash dump capabilities into the
  operating system. These facilities are in the form of low-level 
  libraries for accessing data in system crash dumps, a utility 
  called 'lcrash' for generating system crash dump reports and 
  for interactively examining data in system dumps, and various 
  system scripts necessary for incorporating LKCD into the operating 
  system.


Overview of LKCD Operation
--------------------------

As the system boots up, the /sbin/lkcd script is run twice by the
/etc/rc.d/rc.sysinit startup script; once to save the crash dump, and
a second time to configure the system for crashing.

When '/sbin/lkcd save' runs, the variables in /etc/sysconfig/dump
are read in and the 'lcrash' utility is launched to save the crash
dump to the appropriate dump directory. When '/sbin/lkcd config' is
run, the dump sysconfig variables are read in again and used to open
the dump device and configure the system for crash dumps if a failure
occurs.

The reason why /sbin/lkcd is run twice is due to the boot order that
currently exists in Linux. The save of a crash dump needs to take
place before the swap devices are mounted. In addition, the
configuration and opening of the dump device cannot take place until
after /proc is mounted. Because of this, the logical has to be:

o Save the crash dump (if any)
o Mount the swap partitions
o Mount /proc
o Configure the system for crash dumps


Crash Dump Configuration Options
--------------------------------

There are a number of configurable options that effect the behavior of
LKCD facilities. Please review /etc/sysconfig/dump for more details
on the options available. They are outlined in complete detail in that
file; In short, the options allow you to:

o determine if you want to implement crash dumps in the kernel;
o choose whether to save crash dumps to disk or not;
o change the location where the crash dumps are saved to;
o specify any character dump device you want;
o compress (or not compress) the crash dumps;
o configure the system to panic (or not) after a failure.


Configuring Your System for LKCD
--------------------------------

LKCD adds a kernel configuration option that tells the Linux kernel
whether or not to generate system crash dumps after a system crash. To
enable this option, simply specify "Support kernel crash dump
capabilities" in the Kernel Hacking section of 'make xconfig' or 'make
menuconfig' (or 'make config' for those that prefer a non-GUI/CUI
interface). This turns on crash dump capabilities in the kernel. Once
you have successfully built a kernel capable of generating system
crash dumps, do the following to complete LKCD configuration:

1) Create a dump directory and make sure that the DUMPDIR variable in
   /etc/sysconfig/dump points to this directory. By convention,
   /var/log/dump should be the name of your dump directory, although
   any directory will work (as long as you also modify DUMPDIR in
   /etc/sysconfig/dump so that it references the new directory). If
   the the directory pointed to by DUMPDIR does not exist and a system
   crash occurs, the directory will be created automatically before the
   dump is saved.

2) After creating the dump device and making the dump directory, try
   opening the dump device by running '/sbin/dump config'. You
   should see the following (or something very similar):

   kernel: dump_open(): dump device opened: 0xXXX

   If this is not what you see and instead, you see an error message
   indicating the dump device wasn't opened correctly, go back to
   step 1 and double check to ensure you set things up correctly.
   In addition, if some other error message is reported, validate
   that /dev/dump exists (with major 227, minor 0), and that there
   is a primary swap partition in your /etc/fstab for dumping to.

The system is now ready to save a (possibly compressed) system memory
image to the dump device in the event of a kernel panic or exception.
When the system comes back up, the rc.sysinit script will determine
that a system dump was generated. It will then save a copy of the the
system crash dump, along with a copy of the System.map, Kerntypes, and
current lcrash binary to DUMPDIR, all appended with the current bounds
number.

The kernel code that generates the system crash dump is located in the
drivers/dump/dump_base.c file, and the specific architecture code is in
drivers/dump/dump_<arch>.c. Hooks have also been placed in various
locations to make sure the dumping facility work properly. For more
information, including details on the dump method, compression used,
etc., please read the LKCD FAQ at

    http://oss.sgi.com/projects/lkcd/faq.html.
