mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
hsavmcore: add man pages for hsavmcore and hsavmcore.conf
Signed-off-by: Alexander Egorenkov <egorenar@linux.ibm.com> Reviewed-by: Philipp Rudo <prudo@linux.ibm.com> Acked-by: Jan Höppner <hoeppner@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
This commit is contained in:
Alexander Egorenkov
committed by
Jan Höppner
Jan Höppner
parent
a38d82e8f9
commit
9fb2568134
@@ -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
|
||||
|
||||
|
||||
139
hsavmcore/man/hsavmcore.8
Normal file
139
hsavmcore/man/hsavmcore.8
Normal file
@@ -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)
|
||||
118
hsavmcore/man/hsavmcore.conf.5
Normal file
118
hsavmcore/man/hsavmcore.conf.5
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user