dump

Synopsis:

dump directory
dump |shell_command

Options:

directory: The output directory in the host.

or:

|shell_command: If the first character of the argument is a pipe, the characters that follow it are spawned as a shell command in the host, and the contents of the dump file are written to the shell's standard input.

Description:

On receipt of a SIGUSR2 signal or when triggered by a watchdog (see “Watchdogs” in the “QNX Hypervisor: Protection Features” chapter), write a dump file for a guest hosted in this qvm process instance. If the argument does not start with a pipe (“|”), write the dump file to the directory specified by directory. If the argument starts with pipe, spawn a shell command instead.

The dump file

The dump file is called prefix-YYYYMMDD-hhmmsss.gcore where:

prefix is the name of the VM hosting the guest, as specified by the system option; if this option isn't specified (see system in this chapter), prefix is set to qvm-guest
YYYYMMDD-hhmmss is the host date and time at the moment that the dump is requested

If a file with the name that the qvm process composes for the dump file already exists in the specified directory, the qvm process attempts to generate a unique name by inserting a hyphen and a number from 1 to 9 (-1, -2, ... -9) before the .gcore extension. For example, if the files qnx7-20170821-120619 and qnx7-20170821-120619-1 exist, the qvm process creates a file called qnx7-20170821-120619-2. If the qvm process is unable to create a unique filename, it doesn't create a dump file.

The dump file is output in ELF64 format. A PT_NOTE segment has the register states for the vCPUs, and PT_LOAD segments have the guest memory contents. The format of the PT_NOTE segment is described by the sys/kdump.h public header file.

To interpret the dump file, you can use GDB and kdserver (see kdserver in the QNX Neutrino Utilities Reference). You can also run use -i dump_file to display much more information than usual to assist with troubleshooting. The information displayed in this case includes:

pidin information about the host machine that qvm is running on
information about the version of qvm that is running
the qvm configuration being used
the same output you get when you send SIGUSR1 (QL_QVM_INFO, or information-level, messages)

For more information about this last utility, see the use entry in the Utilities Reference.

Example:

On receipt of a SIGUSR2 signal, the configuration excerpt shown below will direct the guest's dump file contents to a host shell command that compresses these contents (gzip) and then writes the compressed file to stdout, which is the file dump_output.gz:

dump "|gzip >dump_output.gz"

Note: The quotation marks around the argument are used so that when qvm parses the configuration it reads the full shell command as a single qvm argument.