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: all
|
||||||
$(INSTALL) -g $(GROUP) -o $(OWNER) -m 755 hsavmcore \
|
$(INSTALL) -g $(GROUP) -o $(OWNER) -m 755 hsavmcore \
|
||||||
$(DESTDIR)$(USRSBINDIR)
|
$(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
|
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