$Date: 2016-06-29 18:53:05 +0200 (Wed, 29 Jun 2016) $

VBoxManage debugvm

VBoxManage-debugvm 1
VBoxManage-debugvm introspection and guest debugging Oracle VM VirtualBox
`VBoxManage debugvm` uuid|vmname dumpvmcore --filename=name `VBoxManage debugvm` uuid|vmname info item args `VBoxManage debugvm` uuid|vmname injectnmi `VBoxManage debugvm` uuid|vmname log --release--debug group-settings `VBoxManage debugvm` uuid|vmname logdest --release--debug destinations `VBoxManage debugvm` uuid|vmname logflags --release--debug flags `VBoxManage debugvm` uuid|vmname osdetect `VBoxManage debugvm` uuid|vmname osinfo `VBoxManage debugvm` uuid|vmname osdmesg --lines=lines `VBoxManage debugvm` uuid|vmname getregisters --cpu=id reg-set.reg-name `VBoxManage debugvm` uuid|vmname setregisters --cpu=id reg-set.reg-name=value `VBoxManage debugvm` uuid|vmname show --human-readable--sh-export--sh-eval--cmd-set settings-item `VBoxManage debugvm` uuid|vmname stack --cpu=id `VBoxManage debugvm` uuid|vmname statistics --reset --descriptions --pattern=pattern

## Description

The "debugvm" commands are for experts who want to tinker with the exact details of virtual machine execution. Like the VM debugger described in , these commands are only useful if you are very familiar with the details of the PC architecture and how to debug software.

### Common options

The subcommands of `debugvm` all operate on a running virtual machine:

uuid|vmname

  Either the UUID or the name (case sensitive) of a VM.

### debugvm dumpvmcore

Creates a system dump file of the specified VM. This file will have the standard ELF core format (with custom sections); see .

This corresponds to the `writecore` command in the debugger.

`--filename=filename`

  The name of the output file.

### debugvm info

Displays info items relating to the VMM, device emulations and associated drivers.

This corresponds to the `info` command in the debugger.

info

  Name of the info item to display. The special name `help` will list all the available info items and hints about optional arguments.

args

  Optional argument string for the info item handler. Most info items does not take any extra arguments. Arguments not recognized are generally ignored.

### debugvm injectnmi

Causes a non-maskable interrupt (NMI) to be injected into the guest. This might be useful for certain debugging scenarios. What happens exactly is dependent on the guest operating system, but an NMI can crash the whole guest operating system. Do not use unless you know what you're doing.

### debugvm log

Changes the group settings for either debug (`--debug`) or release (`--release`) logger of the VM process.

The group-settings are typically strings on the form `em.e.f.l`, `hm=~0` and `-em.f`. Basic wildcards are supported for group matching. The `all` group is an alias for all the groups.

Please do keep in mind that the group settings are applied as modifications to the current ones.

This corresponds to the `log` command in the debugger.

### debugvm logdest

Changes the destination settings for either debug (`--debug`) or release (`--release`) logger of the VM process. For details on the destination format, the best source is src/VBox/Runtime/common/log/log.cpp.

The destinations is one or more mnemonics, optionally prefixed by "no" to disable them. Some of them take values after a ":" or "=" separator. Multiple mnemonics can be separated by space or given as separate arguments on the command line.

List of available destination:

`file[=file], nofile`

  Specifies a log file. It no filname is given, one will be generated based on the current UTC time and VM process name and placed in the current directory of the VM process. Note that this will currently not have any effect if the log file has already been opened.

`dir=directory, nodir`

  Specifies the output directory for log files. Note that this will currently not have any effect if the log file has already been opened.

`history=count, nohistory`

  A non-zero value enables log historization, with the value specifying how many old log files to keep.

`histsize=bytes`

  The max size of a log file before it is historized. Default is infinite.

`histtime=seconds`

  The max age (in seconds) of a log file before it is historized. Default is infinite.

`ringbuffer, noringbuffer`

  Only log to the log buffer until an explicit flush (e.g. via an assertion) occurs. This is fast and saves diskspace.

`stdout, nostdout`

  Write the log content to standard output.

`stdout, nostdout`

  Write the log content to standard error.

`debugger, nodebugger`

  Write the log content to the debugger, if supported by the host OS.

`com, nocom`

  Writes logging to the COM port. This is only applicable for raw-mode and ring-0 logging.

`user, nouser`

  Custom destination which has no meaning to VM processes..

This corresponds to the `logdest` command in the debugger.

### debugvm logflags

Changes the flags on either debug (`--debug`) or release (`--release`) logger of the VM process. Please note that the modifications are applied onto the existing changes, they are not replacing them.

The flags are a list of flag mnemonics, optionally prefixed by a "no", "!", "~" or "-" to negate their meaning. The "+" prefix can be used to undo previous negation or use as a separator, though better use whitespace or separate arguments for that.

List of log flag mnemonics, with their counter form where applicable (asterisk indicates defaults):

`enabled*, disabled`

  Enables or disables logging.

`buffered, unbuffered*`

  Enabling buffering of log output before it hits the destinations.

`writethrough(/writethru)`

  Whether to open the destination file with writethru buffering settings or not.

`flush`

  Enables flushing of the output file (to disk) after each log statement.

`lockcnts`

  Prefix each log line with lock counts for the current thread.

`cpuid`

  Prefix each log line with the ID of the current CPU.

`pid`

  Prefix each log line with the current process ID.

`flagno`

  Prefix each log line with the numberic flags corresponding to the log statement.

`flag`

  Prefix each log line with the flag mnemonics corresponding to the log statement.

`groupno`

  Prefix each log line with the log group number for the log statement producing it.

`group`

  Prefix each log line with the log group name for the log statement producing it.

`tid`

  Prefix each log line with the current thread identifier.

`thread`

  Prefix each log line with the current thread name.

`time`

  Prefix each log line with the current UTC wall time.

`timeprog`

  Prefix each log line with the current monotonic time since the start of the program.

`msprog`

  Prefix each log line with the current monotonic timestamp value in milliseconds since the start of the program.

`ts`

  Prefix each log line with the current monotonic timestamp value in nanoseconds.

`tsc`

  Prefix each log line with the current CPU timestamp counter (TSC) value.

`rel, abs*`

  Selects the whether `ts` and `tsc` prefixes should be displayed as relative to the previous log line or as absolute time.

`hex*, dec`

  Selects the whether the `ts` and `tsc` prefixes should be formatted as hexadecimal or decimal.

`custom`

  Custom log prefix, has by default no meaning for VM processes.

`usecrlf, uself*`

  Output with DOS style (CRLF) or just UNIX style (LF) line endings.

`overwrite*, append`

  Overwrite the destination file or append to it.

This corresponds to the `logflags` command in the debugger.

### debugvm osdetect

Make the VMM's debugger facility (re)-detect the guest operating system (OS). This will first load all debugger plug-ins.

This corresponds to the `detect` command in the debugger.

### debugvm osinfo

Displays information about the guest operating system (OS) previously detected by the VMM's debugger facility.

### debugvm osdmesg

Displays the guest OS kernel log, if detected and supported.

`--lines=lines`

  Number of lines of the log to display, counting from the end. The default is infinite.

### debugvm getregisters

Retrieves register values for guest CPUs and emulated devices.

reg-set.reg-name

  One of more registers, each having one of the following forms:

  1. register-set.register-name.sub-field

  2. register-set.register-name

  3. cpu-register-name.sub-field

  4. cpu-register-name

  5. all

  The all form will cause all registers to be shown (no sub-fields). The registers names are case-insensitive.

`--cpu=id`

  Selects the CPU register set when specifying just a CPU register (3rd and 4th form). The default is 0.

### debugvm setregisters

Changes register values for guest CPUs and emulated devices.

reg-set.reg-name=value

  One of more register assignment, each having one of the following forms:

  1. register-set.register-name.sub-field=value

  2. register-set.register-name=value

  3. cpu-register-name.sub-field=value

  4. cpu-register-name=value

  The value format should be in the same style as what `getregisters` displays, with the exception that both octal and decimal can be used instead of hexadecimal.

`--cpu=id`

  Selects the CPU register set when specifying just a CPU register (3rd and 4th form). The default is 0.

### debugvm show

Shows logging settings for the VM.

`--human-readable`

  Selects human readable output.

`--sh-export`

  Selects output format as bourne shell style `export` commands.

`--sh-eval`

  Selects output format as bourne shell style `eval` command input.

`--cmd-set`

  Selects output format as DOS style `SET` commands.

settings-item

  What to display. One or more of the following:

  - logdbg-settings - debug log settings.

  - logrel-settings - release log settings.

  - log-settings - alias for both debug and release log settings.

### debugvm stack

Unwinds the guest CPU stacks to the best of our ability. It is recommended to first run the `osdetect` command, as this gives both symbols and perhaps unwind information.

`--cpu=id`

  Selects a single guest CPU to display the stack for. The default is all CPUs.

### debugvm statistics

Displays or resets VMM statistics.

Retrieves register values for guest CPUs and emulated devices.

`--pattern=pattern`

  DOS/NT-style wildcards patterns for selecting statistics. Multiple patterns can be specified by using the '|' (pipe) character as separator.

`--reset`

  Select reset instead of display mode.