diff options
Diffstat (limited to 'Documentation/s390/zfcpdump.txt')
| -rw-r--r-- | Documentation/s390/zfcpdump.txt | 87 |
1 files changed, 87 insertions, 0 deletions
diff --git a/Documentation/s390/zfcpdump.txt b/Documentation/s390/zfcpdump.txt new file mode 100644 index 000000000000..cf45d27c4608 --- /dev/null +++ b/Documentation/s390/zfcpdump.txt | |||
| @@ -0,0 +1,87 @@ | |||
| 1 | s390 SCSI dump tool (zfcpdump) | ||
| 2 | |||
| 3 | System z machines (z900 or higher) provide hardware support for creating system | ||
| 4 | dumps on SCSI disks. The dump process is initiated by booting a dump tool, which | ||
| 5 | has to create a dump of the current (probably crashed) Linux image. In order to | ||
| 6 | not overwrite memory of the crashed Linux with data of the dump tool, the | ||
| 7 | hardware saves some memory plus the register sets of the boot cpu before the | ||
| 8 | dump tool is loaded. There exists an SCLP hardware interface to obtain the saved | ||
| 9 | memory afterwards. Currently 32 MB are saved. | ||
| 10 | |||
| 11 | This zfcpdump implementation consists of a Linux dump kernel together with | ||
| 12 | a userspace dump tool, which are loaded together into the saved memory region | ||
| 13 | below 32 MB. zfcpdump is installed on a SCSI disk using zipl (as contained in | ||
| 14 | the s390-tools package) to make the device bootable. The operator of a Linux | ||
| 15 | system can then trigger a SCSI dump by booting the SCSI disk, where zfcpdump | ||
| 16 | resides on. | ||
| 17 | |||
| 18 | The kernel part of zfcpdump is implemented as a debugfs file under "zcore/mem", | ||
| 19 | which exports memory and registers of the crashed Linux in an s390 | ||
| 20 | standalone dump format. It can be used in the same way as e.g. /dev/mem. The | ||
| 21 | dump format defines a 4K header followed by plain uncompressed memory. The | ||
| 22 | register sets are stored in the prefix pages of the respective cpus. To build a | ||
| 23 | dump enabled kernel with the zcore driver, the kernel config option | ||
| 24 | CONFIG_ZFCPDUMP has to be set. When reading from "zcore/mem", the part of | ||
| 25 | memory, which has been saved by hardware is read by the driver via the SCLP | ||
| 26 | hardware interface. The second part is just copied from the non overwritten real | ||
| 27 | memory. | ||
| 28 | |||
| 29 | The userspace application of zfcpdump can reside e.g. in an intitramfs or an | ||
| 30 | initrd. It reads from zcore/mem and writes the system dump to a file on a | ||
| 31 | SCSI disk. | ||
| 32 | |||
| 33 | To build a zfcpdump kernel use the following settings in your kernel | ||
| 34 | configuration: | ||
| 35 | * CONFIG_ZFCPDUMP=y | ||
| 36 | * Enable ZFCP driver | ||
| 37 | * Enable SCSI driver | ||
| 38 | * Enable ext2 and ext3 filesystems | ||
| 39 | * Disable as many features as possible to keep the kernel small. | ||
| 40 | E.g. network support is not needed at all. | ||
| 41 | |||
| 42 | To use the zfcpdump userspace application in an initramfs you have to do the | ||
| 43 | following: | ||
| 44 | |||
| 45 | * Copy the zfcpdump executable somewhere into your Linux tree. | ||
| 46 | E.g. to "arch/s390/boot/zfcpdump. If you do not want to include | ||
| 47 | shared libraries, compile the tool with the "-static" gcc option. | ||
| 48 | * If you want to include e2fsck, add it to your source tree, too. The zfcpdump | ||
| 49 | application attempts to start /sbin/e2fsck from the ramdisk. | ||
| 50 | * Use an initramfs config file like the following: | ||
| 51 | |||
| 52 | dir /dev 755 0 0 | ||
| 53 | nod /dev/console 644 0 0 c 5 1 | ||
| 54 | nod /dev/null 644 0 0 c 1 3 | ||
| 55 | nod /dev/sda1 644 0 0 b 8 1 | ||
| 56 | nod /dev/sda2 644 0 0 b 8 2 | ||
| 57 | nod /dev/sda3 644 0 0 b 8 3 | ||
| 58 | nod /dev/sda4 644 0 0 b 8 4 | ||
| 59 | nod /dev/sda5 644 0 0 b 8 5 | ||
| 60 | nod /dev/sda6 644 0 0 b 8 6 | ||
| 61 | nod /dev/sda7 644 0 0 b 8 7 | ||
| 62 | nod /dev/sda8 644 0 0 b 8 8 | ||
| 63 | nod /dev/sda9 644 0 0 b 8 9 | ||
| 64 | nod /dev/sda10 644 0 0 b 8 10 | ||
| 65 | nod /dev/sda11 644 0 0 b 8 11 | ||
| 66 | nod /dev/sda12 644 0 0 b 8 12 | ||
| 67 | nod /dev/sda13 644 0 0 b 8 13 | ||
| 68 | nod /dev/sda14 644 0 0 b 8 14 | ||
| 69 | nod /dev/sda15 644 0 0 b 8 15 | ||
| 70 | file /init arch/s390/boot/zfcpdump 755 0 0 | ||
| 71 | file /sbin/e2fsck arch/s390/boot/e2fsck 755 0 0 | ||
| 72 | dir /proc 755 0 0 | ||
| 73 | dir /sys 755 0 0 | ||
| 74 | dir /mnt 755 0 0 | ||
| 75 | dir /sbin 755 0 0 | ||
| 76 | |||
| 77 | * Issue "make image" to build the zfcpdump image with initramfs. | ||
| 78 | |||
| 79 | In a Linux distribution the zfcpdump enabled kernel image must be copied to | ||
| 80 | /usr/share/zfcpdump/zfcpdump.image, where the s390 zipl tool is looking for the | ||
| 81 | dump kernel when preparing a SCSI dump disk. | ||
| 82 | |||
| 83 | If you use a ramdisk copy it to "/usr/share/zfcpdump/zfcpdump.rd". | ||
| 84 | |||
| 85 | For more information on how to use zfcpdump refer to the s390 'Using the Dump | ||
| 86 | Tools book', which is available from | ||
| 87 | http://www.ibm.com/developerworks/linux/linux390. | ||