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. More...
void | dumpHostProcessCore (in wstring filename, in wstring compression)
| Takes a core dump of the VM process on the host. More...
void | info (in wstring name, in wstring args, [retval] out wstring info)
| Interfaces with the info dumpers (DBGFInfo). More...
void | injectNMI ()
| Inject an NMI into a running VT-x/AMD-V VM. More...
void | modifyLogGroups (in wstring settings)
| Modifies the group settings of the debug or release logger. More...
void | modifyLogFlags (in wstring settings)
| Modifies the debug or release logger flags. More...
void | modifyLogDestinations (in wstring settings)
| Modifies the debug or release logger destinations. More...
void | readPhysicalMemory (in long long address, in unsigned long size, [retval] out octet[] bytes)
| Reads guest physical memory, no side effects (MMIO++). More...
void | writePhysicalMemory (in long long address, in unsigned long size, in octet[] bytes)
| Writes guest physical memory, access handles (MMIO++) are ignored. More...
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++). More...
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. More...
void | loadPlugIn (in wstring name, [retval] out wstring plugInName)
| Loads a DBGF plug-in. More...
void | unloadPlugIn (in wstring name)
| Unloads a DBGF plug-in. More...
void | detectOS ([retval] out wstring os)
| Tries to (re-)detect the guest OS kernel. More...
void | queryOSKernelLog (in unsigned long maxMessages, [retval] out wstring dmesg)
| Tries to get the kernel log (dmesg) of the guest OS. More...
void | getRegister (in unsigned long cpuId, in wstring name, [retval] out wstring value)
| Gets one register. More...
void | getRegisters (in unsigned long cpuId, out wstring[] names, out wstring[] values)
| Gets all the registers for the given CPU. More...
void | setRegister (in unsigned long cpuId, in wstring name, in wstring value)
| Gets one register. More...
void | setRegisters (in unsigned long cpuId, in wstring[] names, in wstring[] values)
| Sets zero or more registers atomically. More...
void | dumpGuestStack (in unsigned long cpuId, [retval] out wstring stack)
| Produce a simple stack dump using the current guest state. More...
void | resetStats (in wstring pattern)
| Reset VM statistics. More...
void | dumpStats (in wstring pattern)
| Dumps VM statistics. More...
void | getStats (in wstring pattern, in boolean withDescriptions, [retval] out wstring stats)
| Get the VM statistics in a XMLish format. More...

## Public Attributes
attribute boolean | singleStep
| Switch for enabling single-stepping. More...
attribute boolean | recompileUser
| Switch for forcing code recompilation for user mode code. More...
attribute boolean | recompileSupervisor
| Switch for forcing code recompilation for supervisor mode code. More...
attribute boolean | executeAllInIEM
| Whether to execute all the code in the instruction interpreter. More...
attribute boolean | PATMEnabled
| Switch for enabling and disabling the PATM component. More...
attribute boolean | CSAMEnabled
| Switch for enabling and disabling the CSAM component. More...
attribute boolean | logEnabled
| Switch for enabling and disabling the debug logger. More...
readonly attribute wstring | logDbgFlags
| The debug logger flags. More...
readonly attribute wstring | logDbgGroups
| The debug logger's group settings. More...
readonly attribute wstring | logDbgDestinations
| The debug logger's destination settings. More...
readonly attribute wstring | logRelFlags
| The release logger flags. More...
readonly attribute wstring | logRelGroups
| The release logger's group settings. More...
readonly attribute wstring | logRelDestinations
| The relase logger's destination settings. More...
readonly attribute boolean | HWVirtExEnabled
| Flag indicating whether the VM is currently making use of CPU hardware virtualization extensions. More...
readonly attribute boolean | HWVirtExNestedPagingEnabled
| Flag indicating whether the VM is currently making use of the nested paging CPU hardware virtualization extension. More...
readonly attribute boolean | HWVirtExVPIDEnabled
| Flag indicating whether the VM is currently making use of the VPID VT-x extension. More...
readonly attribute boolean | HWVirtExUXEnabled
| Flag indicating whether the VM is currently making use of the unrestricted execution feature of VT-x. More...
readonly attribute wstring | OSName
| Query the guest OS kernel name as detected by the DBGF. More...
readonly attribute wstring | OSVersion
| Query the guest OS kernel version string as detected by the DBGF. More...
readonly attribute boolean | PAEEnabled
| Flag indicating whether the VM is currently making use of the Physical Address Extension CPU feature. More...
attribute unsigned long | virtualTimeRate
| The rate at which the virtual time runs expressed as a percentage. More...
readonly attribute long long | VM
| Gets the user-mode VM handle, with a reference. More...
readonly attribute long long | uptime
| VM uptime in milliseconds, i.e. More...

## 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 formattings are supported in addition to any special formattings 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 paralell 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.

## ◆ dumpStats()

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

Dumps VM statistics.

Parameters

  pattern | The selection pattern. A bit similar to filename globbing.

## ◆ 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.
  withDescriptions | Whether to include the descriptions.
  stats | The XML document containing the statistics.

## Member Data Documentation

## ◆ singleStep

attribute boolean IMachineDebugger::singleStep

Switch for enabling single-stepping.

## ◆ recompileUser

attribute boolean IMachineDebugger::recompileUser

Switch for forcing code recompilation for user mode code.

## ◆ recompileSupervisor

attribute boolean IMachineDebugger::recompileSupervisor

Switch for forcing code recompilation for supervisor mode code.

## ◆ executeAllInIEM

attribute boolean IMachineDebugger::executeAllInIEM

Whether to execute all the code in the instruction interpreter.

This is mainly for testing the interpreter and not an execution mode intended for general consumption.

## ◆ PATMEnabled

attribute boolean IMachineDebugger::PATMEnabled

Switch for enabling and disabling the PATM component.

## ◆ CSAMEnabled

attribute boolean IMachineDebugger::CSAMEnabled

Switch for enabling and disabling the CSAM component.

## ◆ 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 relase logger's destination settings.

## ◆ HWVirtExEnabled

readonly attribute boolean IMachineDebugger::HWVirtExEnabled

Flag indicating whether the VM is currently making use of CPU hardware virtualization extensions.

## ◆ 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%.

## ◆ VM

readonly attribute long long IMachineDebugger::VM

Gets the user-mode VM handle, with a reference.

Must be passed to VMR3ReleaseUVM when done. This is only for internal use while we carve the details of this interface.

## ◆ 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.