VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IMachineDebugger Interface Reference
Inheritance diagram for IMachineDebugger:

## Public Member Functions
void | dumpGuestCore (in wstring filename, in wstring compression)
| Takes a core dump of the guest.
void | dumpHostProcessCore (in wstring filename, in wstring compression)
| Takes a core dump of the VM process on the host.
void | info (in wstring name, in wstring args, [retval] out wstring info)
| Interfaces with the info dumpers (DBGFInfo).
void | injectNMI ()
| Inject an NMI into a running VT-x/AMD-V VM.
void | modifyLogGroups (in wstring settings)
| Modifies the group settings of the debug or release logger.
void | modifyLogFlags (in wstring settings)
| Modifies the debug or release logger flags.
void | modifyLogDestinations (in wstring settings)
| Modifies the debug or release logger destinations.
void | readPhysicalMemory (in long long address, in unsigned long size, [retval] out octet[] bytes)
| Reads guest physical memory, no side effects (MMIO++).
void | writePhysicalMemory (in long long address, in unsigned long size, in octet[] bytes)
| Writes guest physical memory, access handles (MMIO++) are ignored.
void | readVirtualMemory (in unsigned long cpuId, in long long address, in unsigned long size, [retval] out octet[] bytes)
| Reads guest virtual memory, no side effects (MMIO++).
void | writeVirtualMemory (in unsigned long cpuId, in long long address, in unsigned long size, in octet[] bytes)
| Writes guest virtual memory, access handles (MMIO++) are ignored.
void | loadPlugIn (in wstring name, [retval] out wstring plugInName)
| Loads a DBGF plug-in.
void | unloadPlugIn (in wstring name)
| Unloads a DBGF plug-in.
void | detectOS ([retval] out wstring os)
| Tries to (re-)detect the guest OS kernel.
void | queryOSKernelLog (in unsigned long maxMessages, [retval] out wstring dmesg)
| Tries to get the kernel log (dmesg) of the guest OS.
void | getRegister (in unsigned long cpuId, in wstring name, [retval] out wstring value)
| Gets one register.
void | getRegisters (in unsigned long cpuId, out wstring[] names, out wstring[] values)
| Gets all the registers for the given CPU.
void | setRegister (in unsigned long cpuId, in wstring name, in wstring value)
| Gets one register.
void | setRegisters (in unsigned long cpuId, in wstring[] names, in wstring[] values)
| Sets zero or more registers atomically.
void | dumpGuestStack (in unsigned long cpuId, [retval] out wstring stack)
| Produce a simple stack dump using the current guest state.
void | resetStats (in wstring pattern)
| Reset VM statistics.
void | dumpStats (in wstring pattern)
| Dumps VM statistics.
void | getStats (in wstring pattern, in boolean withDescriptions, [retval] out wstring stats)
| Get the VM statistics in a XMLish format.
void | getCPULoad (in unsigned long cpuId, out unsigned long pctExecuting, out unsigned long pctHalted, out unsigned long pctOther, [retval] out long long msInterval)
| Get the load percentages (as observed by the VMM) for all virtual CPUs or a specific one.
void | takeGuestSample (in wstring filename, in unsigned long usInterval, in long long usSampleTime, [retval] out IProgress progress)
| Creates a sample report of the guest and emulated device activity.
void | getUVMAndVMMFunctionTable (in long long magicVersion, out long long VMMFunctionTable, [retval] out long long UVM)
| Gets the user-mode VM handle, with a reference, and the VMM function table.

## Public Attributes
attribute boolean | singleStep
| Switch for enabling single-stepping.
attribute boolean | executeAllInIEM
| Whether to execute all the code in the instruction interpreter.
attribute boolean | logEnabled
| Switch for enabling and disabling the debug logger.
readonly attribute wstring | logDbgFlags
| The debug logger flags.
readonly attribute wstring | logDbgGroups
| The debug logger's group settings.
readonly attribute wstring | logDbgDestinations
| The debug logger's destination settings.
readonly attribute wstring | logRelFlags
| The release logger flags.
readonly attribute wstring | logRelGroups
| The release logger's group settings.
readonly attribute wstring | logRelDestinations
| The release logger's destination settings.
readonly attribute VMExecutionEngine | executionEngine
| Gets the main execution engine of the VM.
readonly attribute boolean | HWVirtExNestedPagingEnabled
| Flag indicating whether the VM is currently making use of the nested paging CPU hardware virtualization extension.
readonly attribute boolean | HWVirtExVPIDEnabled
| Flag indicating whether the VM is currently making use of the VPID VT-x extension.
readonly attribute boolean | HWVirtExUXEnabled
| Flag indicating whether the VM is currently making use of the unrestricted execution feature of VT-x.
readonly attribute wstring | OSName
| Query the guest OS kernel name as detected by the DBGF.
readonly attribute wstring | OSVersion
| Query the guest OS kernel version string as detected by the DBGF.
readonly attribute boolean | PAEEnabled
| Flag indicating whether the VM is currently making use of the Physical Address Extension CPU feature.
attribute unsigned long | virtualTimeRate
| The rate at which the virtual time runs expressed as a percentage.
readonly attribute long long | uptime
| VM uptime in milliseconds, i.e.
attribute boolean | recompiledIEMExecution
| Whether to use the recompiler when executing in the interpreter.

## Member Function Documentation

## ◆ dumpGuestCore()

void IMachineDebugger::dumpGuestCore | ( | in wstring | filename,
|  | in wstring | compression
| ) |  |

Takes a core dump of the guest.

See include/VBox/dbgfcorefmt.h for details on the file format.

Parameters

  filename | The name of the output file. The file must not exist.
  compression | Reserved for future compression method indicator.

## ◆ dumpHostProcessCore()

void IMachineDebugger::dumpHostProcessCore | ( | in wstring | filename,
|  | in wstring | compression
| ) |  |

Takes a core dump of the VM process on the host.

This feature is not implemented in the 4.0.0 release but it may show up in a dot release.

Parameters

  filename | The name of the output file. The file must not exist.
  compression | Reserved for future compression method indicator.

## ◆ info()

void IMachineDebugger::info | ( | in wstring | name,
|  | in wstring | args,
|  | [retval] out wstring | info
| ) |  |

Interfaces with the info dumpers (DBGFInfo).

This feature is not implemented in the 4.0.0 release but it may show up in a dot release.

Parameters

  name | The name of the info item.
  args | Arguments to the info dumper.
  info | The into string.

## ◆ injectNMI()

void IMachineDebugger::injectNMI | ( |  | ) |

Inject an NMI into a running VT-x/AMD-V VM.

## ◆ modifyLogGroups()

void IMachineDebugger::modifyLogGroups | ( | in wstring | settings | ) |

Modifies the group settings of the debug or release logger.

Parameters

  settings | The group settings string. See iprt/log.h for details. To target the release logger, prefix the string with "release:".

## ◆ modifyLogFlags()

void IMachineDebugger::modifyLogFlags | ( | in wstring | settings | ) |

Modifies the debug or release logger flags.

Parameters

  settings | The flags settings string. See iprt/log.h for details. To target the release logger, prefix the string with "release:".

## ◆ modifyLogDestinations()

void IMachineDebugger::modifyLogDestinations | ( | in wstring | settings | ) |

Modifies the debug or release logger destinations.

Parameters

  settings | The destination settings string. See iprt/log.h for details. To target the release logger, prefix the string with "release:".

## ◆ readPhysicalMemory()

void IMachineDebugger::readPhysicalMemory | ( | in long long | address,
|  | in unsigned long | size,
|  | [retval] out octet[] | bytes
| ) |  |

Reads guest physical memory, no side effects (MMIO++).

This feature is not implemented in the 4.0.0 release but may show up in a dot release.

Parameters

  address | The guest physical address.
  size | The number of bytes to read.
  bytes | The bytes read.

## ◆ writePhysicalMemory()

void IMachineDebugger::writePhysicalMemory | ( | in long long | address,
|  | in unsigned long | size,
|  | in octet[] | bytes
| ) |  |

Writes guest physical memory, access handles (MMIO++) are ignored.

This feature is not implemented in the 4.0.0 release but may show up in a dot release.

Parameters

  address | The guest physical address.
  size | The number of bytes to read.
  bytes | The bytes to write.

## ◆ readVirtualMemory()

void IMachineDebugger::readVirtualMemory | ( | in unsigned long | cpuId,
|  | in long long | address,
|  | in unsigned long | size,
|  | [retval] out octet[] | bytes
| ) |  |

Reads guest virtual memory, no side effects (MMIO++).

This feature is not implemented in the 4.0.0 release but may show up in a dot release.

Parameters

  cpuId | The identifier of the Virtual CPU.
  address | The guest virtual address.
  size | The number of bytes to read.
  bytes | The bytes read.

## ◆ writeVirtualMemory()

void IMachineDebugger::writeVirtualMemory | ( | in unsigned long | cpuId,
|  | in long long | address,
|  | in unsigned long | size,
|  | in octet[] | bytes
| ) |  |

Writes guest virtual memory, access handles (MMIO++) are ignored.

This feature is not implemented in the 4.0.0 release but may show up in a dot release.

Parameters

  cpuId | The identifier of the Virtual CPU.
  address | The guest virtual address.
  size | The number of bytes to read.
  bytes | The bytes to write.

## ◆ loadPlugIn()

void IMachineDebugger::loadPlugIn | ( | in wstring | name,
|  | [retval] out wstring | plugInName
| ) |  |

Loads a DBGF plug-in.

Parameters

  name | The plug-in name or DLL. Special name 'all' loads all installed plug-ins.
  plugInName | The name of the loaded plug-in.

## ◆ unloadPlugIn()

void IMachineDebugger::unloadPlugIn | ( | in wstring | name | ) |

Unloads a DBGF plug-in.

Parameters

  name | The plug-in name or DLL. Special name 'all' unloads all plug-ins.

## ◆ detectOS()

void IMachineDebugger::detectOS | ( | [retval] out wstring | os | ) |

Tries to (re-)detect the guest OS kernel.

This feature is not implemented in the 4.0.0 release but may show up in a dot release.

Parameters

  os | The detected OS kernel on success.

## ◆ queryOSKernelLog()

void IMachineDebugger::queryOSKernelLog | ( | in unsigned long | maxMessages,
|  | [retval] out wstring | dmesg
| ) |  |

Tries to get the kernel log (dmesg) of the guest OS.

Parameters

  maxMessages | Max number of messages to return, counting from the end of the log. If 0, there is no limit.
  dmesg | The kernel log.

## ◆ getRegister()

void IMachineDebugger::getRegister | ( | in unsigned long | cpuId,
|  | in wstring | name,
|  | [retval] out wstring | value
| ) |  |

Gets one register.

Parameters

  cpuId | The identifier of the Virtual CPU.
  name | The register name, case is ignored.
  value | The register value. This is usually a hex value (always 0x prefixed) but other format may be used for floating point registers (TBD).

## ◆ getRegisters()

void IMachineDebugger::getRegisters | ( | in unsigned long | cpuId,
|  | out wstring[] | names,
|  | out wstring[] | values
| ) |  |

Gets all the registers for the given CPU.

Parameters

  cpuId | The identifier of the Virtual CPU.
  names | Array containing the lowercase register names.
  values | Array parallel to the names holding the register values as if the register was returned by IMachineDebugger::getRegister.

## ◆ setRegister()

void IMachineDebugger::setRegister | ( | in unsigned long | cpuId,
|  | in wstring | name,
|  | in wstring | value
| ) |  |

Gets one register.

This feature is not implemented in the 4.0.0 release but may show up in a dot release.

Parameters

  cpuId | The identifier of the Virtual CPU.
  name | The register name, case is ignored.
  value | The new register value. Hexadecimal, decimal and octal formats are supported in addition to any special formats returned by the getters.

## ◆ setRegisters()

void IMachineDebugger::setRegisters | ( | in unsigned long | cpuId,
|  | in wstring[] | names,
|  | in wstring[] | values
| ) |  |

Sets zero or more registers atomically.

This feature is not implemented in the 4.0.0 release but may show up in a dot release.

Parameters

  cpuId | The identifier of the Virtual CPU.
  names | Array containing the register names, case ignored.
  values | Array parallel to the names holding the register values. See IMachineDebugger::setRegister for formatting guidelines.

## ◆ dumpGuestStack()

void IMachineDebugger::dumpGuestStack | ( | in unsigned long | cpuId,
|  | [retval] out wstring | stack
| ) |  |

Produce a simple stack dump using the current guest state.

This feature is not implemented in the 4.0.0 release but may show up in a dot release.

Parameters

  cpuId | The identifier of the Virtual CPU.
  stack | String containing the formatted stack dump.

## ◆ resetStats()

void IMachineDebugger::resetStats | ( | in wstring | pattern | ) |

Reset VM statistics.

Parameters

  pattern | The selection pattern. A bit similar to filename globbing. Wildcards are '*' and '?', where the asterisk matches zero or more characters and question mark matches exactly one character. Multiple pattern can be joined by putting '|' between them.

## ◆ dumpStats()

void IMachineDebugger::dumpStats | ( | in wstring | pattern | ) |

Dumps VM statistics.

Parameters

  pattern | The selection pattern. A bit similar to filename globbing. Wildcards are '*' and '?', where the asterisk matches zero or more characters and question mark matches exactly one character. Multiple pattern can be joined by putting '|' between them.

## ◆ getStats()

void IMachineDebugger::getStats | ( | in wstring | pattern,
|  | in boolean | withDescriptions,
|  | [retval] out wstring | stats
| ) |  |

Get the VM statistics in a XMLish format.

Parameters

  pattern | The selection pattern. A bit similar to filename globbing. Wildchars are '*' and '?', where the asterisk matches zero or more characters and question mark matches exactly one character. Multiple pattern can be joined by putting '|' between them.
  withDescriptions | Whether to include the descriptions.
  stats | The XML document containing the statistics.

## ◆ getCPULoad()

void IMachineDebugger::getCPULoad | ( | in unsigned long | cpuId,
|  | out unsigned long | pctExecuting,
|  | out unsigned long | pctHalted,
|  | out unsigned long | pctOther,
|  | [retval] out long long | msInterval
| ) |  |

Get the load percentages (as observed by the VMM) for all virtual CPUs or a specific one.

Parameters

  cpuId | The ID of the virtual CPU to retrieve stats for, pass 0x7fffffff or higher for the average accross all CPUs.
  pctExecuting | Percentage of the interval that the CPU(s) spend executing guest code.
  pctHalted | Percentage of the interval that the CPU(s) spend halted.
  pctOther | Percentage of the interval that the CPU(s) preempted by the host scheduler, on virtualization overhead and on other tasks.
  msInterval | The interval the percentage was calculated over in milliseconds

## ◆ takeGuestSample()

void IMachineDebugger::takeGuestSample | ( | in wstring | filename,
|  | in unsigned long | usInterval,
|  | in long long | usSampleTime,
|  | [retval] out IProgress | progress
| ) |  |

Creates a sample report of the guest and emulated device activity.

Parameters

  filename | The file to dump the report to.
  usInterval | The sample interval.
  usSampleTime | The number of microseconds to sample.
  progress | The progress object on return.

## ◆ getUVMAndVMMFunctionTable()

void IMachineDebugger::getUVMAndVMMFunctionTable | ( | in long long | magicVersion,
|  | out long long | VMMFunctionTable,
|  | [retval] out long long | UVM
| ) |  |

Gets the user-mode VM handle, with a reference, and the VMM function table.

The VM handle must be passed to VMR3ReleaseUVM when done. This can only be called from within the VM process, remote calls will always fail.

Parameters

  magicVersion | The VMMR3VTABLE_MAGIC_VERSION value of the caller. The method will fail if this is not compatible with the VMM function table.
  VMMFunctionTable | The VMM function table address.
  UVM | The user-mode VM handle.

## Member Data Documentation

## ◆ singleStep

attribute boolean IMachineDebugger::singleStep

Switch for enabling single-stepping.

## ◆ executeAllInIEM

attribute boolean IMachineDebugger::executeAllInIEM

Whether to execute all the code in the instruction interpreter.

When `true` the VM execution engine changes to VMExecutionEngine::Interpreter (or VMExecutionEngine::Recompiler when IMachineDebugger::recompiledIEMExecution is set to `true`).

This is mainly for temporarily testing the interpreter and its recompiler.

See also IMachine::VMExecutionEngine for how to permanently configure a VM to run in VMExecutionEngine::Interpreter mode.

## ◆ logEnabled

attribute boolean IMachineDebugger::logEnabled

Switch for enabling and disabling the debug logger.

## ◆ logDbgFlags

readonly attribute wstring IMachineDebugger::logDbgFlags

The debug logger flags.

## ◆ logDbgGroups

readonly attribute wstring IMachineDebugger::logDbgGroups

The debug logger's group settings.

## ◆ logDbgDestinations

readonly attribute wstring IMachineDebugger::logDbgDestinations

The debug logger's destination settings.

## ◆ logRelFlags

readonly attribute wstring IMachineDebugger::logRelFlags

The release logger flags.

## ◆ logRelGroups

readonly attribute wstring IMachineDebugger::logRelGroups

The release logger's group settings.

## ◆ logRelDestinations

readonly attribute wstring IMachineDebugger::logRelDestinations

The release logger's destination settings.

## ◆ executionEngine

readonly attribute VMExecutionEngine IMachineDebugger::executionEngine

Gets the main execution engine of the VM.

## ◆ HWVirtExNestedPagingEnabled

readonly attribute boolean IMachineDebugger::HWVirtExNestedPagingEnabled

Flag indicating whether the VM is currently making use of the nested paging CPU hardware virtualization extension.

## ◆ HWVirtExVPIDEnabled

readonly attribute boolean IMachineDebugger::HWVirtExVPIDEnabled

Flag indicating whether the VM is currently making use of the VPID VT-x extension.

## ◆ HWVirtExUXEnabled

readonly attribute boolean IMachineDebugger::HWVirtExUXEnabled

Flag indicating whether the VM is currently making use of the unrestricted execution feature of VT-x.

## ◆ OSName

readonly attribute wstring IMachineDebugger::OSName

Query the guest OS kernel name as detected by the DBGF.

This feature is not implemented in the 4.0.0 release but may show up in a dot release.

## ◆ OSVersion

readonly attribute wstring IMachineDebugger::OSVersion

Query the guest OS kernel version string as detected by the DBGF.

This feature is not implemented in the 4.0.0 release but may show up in a dot release.

## ◆ PAEEnabled

readonly attribute boolean IMachineDebugger::PAEEnabled

Flag indicating whether the VM is currently making use of the Physical Address Extension CPU feature.

## ◆ virtualTimeRate

attribute unsigned long IMachineDebugger::virtualTimeRate

The rate at which the virtual time runs expressed as a percentage.

The accepted range is 2% to 20000%.

## ◆ uptime

readonly attribute long long IMachineDebugger::uptime

VM uptime in milliseconds, i.e.

time in which it could have been executing guest code. Excludes the time when the VM was paused.

## ◆ recompiledIEMExecution

attribute boolean IMachineDebugger::recompiledIEMExecution

Whether to use the recompiler when executing in the interpreter.

This is used together with IMachineDebugger::executeAllInIEM to temporarily change the main VM execution engine to VMExecutionEngine::Recompiler.

If the VM is configured to run in VMExecutionEngine::Interpreter via IMachine::VMExecutionEngine, setting this to `true` temporarily changes it to VMExecutionEngine::Recompiler.

This mainly for testing the instruction interpreter in recompiler mode.

See also IMachine::VMExecutionEngine for how to permanently configure a VM to run in VMExecutionEngine::Recompiler mode.