1The s390 SCSI dump tool (zfcpdump)
2
3System z machines (z900 or higher) provide hardware support for creating system
4dumps on SCSI disks. The dump process is initiated by booting a dump tool, which
5has to create a dump of the current (probably crashed) Linux image. In order to
6not overwrite memory of the crashed Linux with data of the dump tool, the
7hardware saves some memory plus the register sets of the boot CPU before the
8dump tool is loaded. There exists an SCLP hardware interface to obtain the saved
9memory afterwards. Currently 32 MB are saved.
10
11This zfcpdump implementation consists of a Linux dump kernel together with
12a user space dump tool, which are loaded together into the saved memory region
13below 32 MB. zfcpdump is installed on a SCSI disk using zipl (as contained in
14the s390-tools package) to make the device bootable. The operator of a Linux
15system can then trigger a SCSI dump by booting the SCSI disk, where zfcpdump
16resides on.
17
18The kernel part of zfcpdump is implemented as a debugfs file under "zcore/mem",
19which exports memory and registers of the crashed Linux in an s390
20standalone dump format. It can be used in the same way as e.g. /dev/mem. The
21dump format defines a 4K header followed by plain uncompressed memory. The
22register sets are stored in the prefix pages of the respective CPUs. To build a
23dump enabled kernel with the zcore driver, the kernel config option
24CONFIG_CRASH_DUMP has to be set. When reading from "zcore/mem", the part of
25memory, which has been saved by hardware is read by the driver via the SCLP
26hardware interface. The second part is just copied from the non overwritten real
27memory.
28
29Since kernel version 3.12 also the /proc/vmcore file can also be used to access
30the dump.
31
32To get a valid zfcpdump kernel configuration use "make zfcpdump_defconfig".
33
34The s390 zipl tool looks for the zfcpdump kernel and optional initrd/initramfs
35under the following locations:
36
37* kernel:  <zfcpdump directory>/zfcpdump.image
38* ramdisk: <zfcpdump directory>/zfcpdump.rd
39
40The zfcpdump directory is defined in the s390-tools package.
41
42The user space application of zfcpdump can reside in an intitramfs or an
43initrd. It can also be included in a built-in kernel initramfs. The application
44reads from /proc/vmcore or zcore/mem and writes the system dump to a SCSI disk.
45
46The s390-tools package version 1.24.0 and above builds an external zfcpdump
47initramfs with a user space application that writes the dump to a SCSI
48partition.
49
50For more information on how to use zfcpdump refer to the s390 'Using the Dump
51Tools book', which is available from
52http://www.ibm.com/developerworks/linux/linux390.
53