diff --git a/hsavmcore/Makefile b/hsavmcore/Makefile index 1ace3c32..fc10c124 100644 --- a/hsavmcore/Makefile +++ b/hsavmcore/Makefile @@ -82,6 +82,10 @@ hsavmcore: $(OBJECTS) $(libs) install: all $(INSTALL) -g $(GROUP) -o $(OWNER) -m 755 hsavmcore \ $(DESTDIR)$(USRSBINDIR) + $(INSTALL) -g $(GROUP) -o $(OWNER) -m 644 man/hsavmcore.8 \ + $(DESTDIR)$(MANDIR)/man8 + $(INSTALL) -g $(GROUP) -o $(OWNER) -m 644 man/hsavmcore.conf.5 \ + $(DESTDIR)$(MANDIR)/man5 endif # HAVE_FUSE diff --git a/hsavmcore/man/hsavmcore.8 b/hsavmcore/man/hsavmcore.8 new file mode 100644 index 00000000..8587aa06 --- /dev/null +++ b/hsavmcore/man/hsavmcore.8 @@ -0,0 +1,139 @@ +.\" Copyright 2021 IBM Corp. +.\" s390-tools is free software; you can redistribute it and/or modify +.\" it under the terms of the MIT license. See LICENSE for details. +.\" +.TH HSAVMCORE 8 "May 2021" "s390-tools" +. +.SH NAME +hsavmcore - Enable kdump to release the HSA memory early in the dump process +. +.SH SYNOPSIS +.B hsavmcore +.RI [ OPTIONS ] +. +.SH DESCRIPTION +.B hsavmcore +is designed to make the dump process with kdump more efficient. +The HSA memory contains a part of the production kernel's memory. +Use hsavmcore to cache this information and release HSA memory early in the process. +.PP +Depending on the size of the production kernel's memory, writing the dump to persistent +storage can be time consuming and prevent the HSA memory from being reused by other LPARs. +. +The +.B hsavmcore +tool performs these steps: +.IP " 1)" +Read the size of the HSA memory from +.B /sys/kernel/debug/zcore/hsa. +.IP " 2)" +Cache the HSA memory content contained in +.B /proc/vmcore +either in regular memory or within the file system. +.IP " 3)" +Releases the HSA memory by writing to +.B /sys/kernel/debug/zcore/hsa. +.PP +At this stage, the HSA memory region is unavailable to +.B /proc/vmcore +and cannot be used by kdump. +. +The +.B hsavmcore +tool now combines the cached HSA memory and the non-HSA memory from the original +.B /proc/vmcore +to create a replacement for +.B /proc/vmcore. +. +The replacement +.B /proc/vmcore +can be processed as usual. +. +.SH OPTIONS +.TP +\fB\-h\fP or \fB\-\-help\fP +Print usage information and exit. +. +.TP +\fB\-v\fP or \fB\-\-version\fP +Print version information and exit. +. +.TP +\fB\-V\fP or \fB\-\-verbose\fP +Print verbose messages to stdout. Repeat this option for increased verbosity +from just error messages to also include warning, information, debug, and trace messages. +This option is intended for debugging. +. +.TP +\fB\-c\fP or \fB\-\-config\fP \fICONFIGFILE\fP +Path to the configuration file. By default, no configuration file is used. +. +.TP +\fB\-C\fP or \fB\-\-vmcore\fP \fIVMCOREFILE\fP +Path to the vmcore file. Default: +.B /proc/vmcore. +. +.TP +\fB\-H\fP or \fB\-\-hsa\fP \fIZCOREHSAFILE\fP +Path to the zcore HSA file. Default: +.B /sys/kernel/debug/zcore/hsa. +. +.TP +\fB\-W\fP or \fB\-\-workdir\fP \fIWORKDIR\fP +Path to the work directory where temporary files can be stored. Default: +.B /var/crash. +. +.TP +\fB\-B\fP or \fB\-\-bmvmcore\fP \fIVMCOREFILE\fP +Path to the target of the bind mount for the replacement vmcore file. Default: +.B /proc/vmcore. +. +.TP +\fB\-S\fP or \fB\-\-swap\fP \fIPATH\fP +Path to a swap device or file. The specified swap device or file must exist and have the proper +swap format. Default: no swap device or file is activated. +. +.TP +\fB\-T\fP or \fB\-\-hsasize\fP \fIHSASIZE\fP +HSA size in bytes. Used for testing purposes. Default: -1 (read from the zcore HSA file). +. +.TP +\fB\-D\fP or \fB\-\-dbgfsmnt\fP +Mount the debug file system. Default: the debug file system is not mounted. +. +.TP +\fB\-F\fP or \fB\-\-hsamem\fP +Cache the HSA memory in regular memory. Default: the HSA memory is cached as a file +within WORKDIR. +. +.TP +\fB\-R\fP or \fB\-\-norelhsa\fP +Do NOT release the HSA memory after caching. Default: the HSA memory is released. +. +.TP +\fB\-N\fP or \fB\-\-nobindmnt\fP +Do NOT replace the system's vmcore file. Default: the system's vmcore file is replaced. +. +.TP +\fB\-G\fP or \fB\-\-fusedbg\fP +Enable FUSE debugging. Default: FUSE debugging is disabled. +.RE +. +.SH EXAMPLES +.TP +.B To run hsavmcore on a kdump system during a stand-alone dump with default parameters: +.RS 4 +hsavmcore +.br +makedumpfile \-d 31 /proc/vmcore test-dump.elf +.RE +.TP +.B To test hsavmcore with a vmcore copy and without being in a kdump system (for debugging): +.RS 4 +hsavmcore \-VVV \-T 0x1ffff000 \-C vmcore-dump.elf \-N \-R +.br +makedumpfile \-d 31 /tmp/hsavmcore-overlay/vmcore test-dump.elf +.RE + +.SH SEE ALSO +.BR hsavmcore.conf (5) diff --git a/hsavmcore/man/hsavmcore.conf.5 b/hsavmcore/man/hsavmcore.conf.5 new file mode 100644 index 00000000..7abc356d --- /dev/null +++ b/hsavmcore/man/hsavmcore.conf.5 @@ -0,0 +1,118 @@ +.\" Copyright 2021 IBM Corp. +.\" s390-tools is free software; you can redistribute it and/or modify +.\" it under the terms of the MIT license. See LICENSE for details. +.\" +.TH HSAVMCORE.CONF 5 "May 2021" "s390-tools" +.SH NAME +hsavmcore.conf \- Configuration file for the hsavmcore tool +. +.SH DESCRIPTION +The +.B hsavmcore.conf +configuration file contains the configuration information for +the +.B hsavmcore +tool. + +All specifications in the configuration file are optional. +The command defaults apply for omitted parameters. +. +.SS "verbose" +This parameter sets the verbosity level of the output messages. +The following pre-defined numeric values can be used: +. +.RS 2 +.IP "-" 2 +\fB0\fP - show only error messages (default) +.IP "-" 2 +\fB1\fP - show error and warning messages +.IP "-" 2 +\fB2\fP - show error, warning and information messages +.IP "-" 2 +\fB3\fP - show error, warning, information and debug messages +.IP "-" 2 +\fB4\fP - show error, warning, information, debug and trace messages +.RE +.PP +. +.SS "mount_debugfs" +Mount (1) or do not mount (0) debugfs. Use this configuration if the kdump kernel +does not mount the debugfs during the boot process. +. +.SS "workdir" +Specifies a work directory on the kdump system where the hsavmcore tool can create +temporary files. This specification is required if +.B use_hsa_mem +is set to 0. +. +.SS "use_hsa_mem" +Cache the HSA memory in regular memory (1) or in a file on a file system (0). +. +.SS "hsa_size" +Specify a value, in bytes, for the HSA memory size instead of reading the size +from +.B /sys/kernel/debug/zcore/hsa. +This parameter is intended only to test +the +.B hsavmcore +tool without being in a kdump kernel. Specifying -1 falls back +to reading the size from +.B /sys/kernel/debug/zcore/hsa. +. +.SS "release_hsa" +Release (1) or do not release (0) the HSA memory after it is cached by +the +.B hsavmcore +tool. +. +.SS "bind_mount_vmcore" +Replace (1) the original vmcore file with the new file created by the +.B hsavmcore +tool or keep the original file (0), which no longer contains the information +from the HSA memory. Set this parameter to 1 if you intend to use kdump tools to +create a core dump. +. +.SS "swap" +Specify a swap device or file through its path in a kdump system. +The specified swap device or file must exist and have the proper swap format. +You might need a swap device because the amount of memory available in the kdump +kernel during a stand-alone dump is limited to the size of the HSA memory. +. +.SS "fuse_debug" +Enable (1) or disable (0) fuse debugging. +. +.SH EXAMPLES +A complete configuration file could look like this: + +.nf +------------------------------ config file start ------------------------------ +# Example configuration for hsavmcore + +# 0 - ERROR +# 1 - WARN +# 2 - INFO +# 3 - DEBUG +# 4 - TRACE +verbose = 3 + +workdir = /var/crash + +mount_debugfs = 1 + +use_hsa_mem = 1 + +hsa_size = -1 +release_hsa = 1 + +bind_mount_vmcore = 1 + +swap = /dev/disk/by-uuid/3cf6630b-4c4d-49ac-a0ae-0f5484cb5721 +#swap = /swap.img + +fuse_debug = 0 +------------------------------ config file end ------------------------------ +.fi + +. +.SH SEE ALSO +.BR hsavmcore (8)