Public Member Functions | Public Attributes

# IMachineDebugger Interface Reference

List of all members.

## 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 | detectOS ([retval] out wstring os)
| Tries to (re-)detect the guest OS kernel.
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, out wstring stats)
| Get the VM statistics in a XMLish format.
## Public Attributes
attribute boolean | singleStep
| Switch for enabling single-stepping.
attribute boolean | recompileUser
| Switch for forcing code recompilation for user mode code.
attribute boolean | recompileSupervisor
| Switch for forcing code recompilation for supervisor mode code.
attribute boolean | PATMEnabled
| Switch for enabling and disabling the PATM component.
attribute boolean | CSAMEnabled
| Switch for enabling and disabling the CSAM component.
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 relase logger's destination settings.
readonly attribute boolean | HWVirtExEnabled
| Flag indicating whether the VM is currently making use of CPU hardware virtualization extensions.
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 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 | VM
| Gets the VM handle.

## Member Function Documentation

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.

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.

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.

void IMachineDebugger::injectNMI | ( |  | ) |

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

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:".

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:".

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:".

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.

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.

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.

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.

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.

void IMachineDebugger::getRegister | ( | in unsigned long | cpuId,
|  | in wstring | name,
|  | [retval] out 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 register value. This is usually a hex value (always 0x prefixed) but other format may be used for floating point registers (TBD).

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

Gets all the registers for the given CPU.

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 lowercase register names.
  | values | Array paralell to the names holding the register values as if the register was returned by IMachineDebugger::getRegister.

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.

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.

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.

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

Reset VM statistics.

Parameters:

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

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

Dumps VM statistics.

Parameters:

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

void IMachineDebugger::getStats | ( | in wstring | pattern,
|  | in boolean | withDescriptions,
|  | 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

attribute boolean IMachineDebugger::singleStep

Switch for enabling single-stepping.

attribute boolean IMachineDebugger::recompileUser

Switch for forcing code recompilation for user mode code.

attribute boolean IMachineDebugger::recompileSupervisor

Switch for forcing code recompilation for supervisor mode code.

attribute boolean IMachineDebugger::PATMEnabled

Switch for enabling and disabling the PATM component.

attribute boolean IMachineDebugger::CSAMEnabled

Switch for enabling and disabling the CSAM component.

attribute boolean IMachineDebugger::logEnabled

Switch for enabling and disabling the debug logger.

readonly attribute wstring IMachineDebugger::logDbgFlags

The debug logger flags.

readonly attribute wstring IMachineDebugger::logDbgGroups

The debug logger's group settings.

readonly attribute wstring IMachineDebugger::logDbgDestinations

The debug logger's destination settings.

readonly attribute wstring IMachineDebugger::logRelFlags

The release logger flags.

readonly attribute wstring IMachineDebugger::logRelGroups

The release logger's group settings.

readonly attribute wstring IMachineDebugger::logRelDestinations

The relase logger's destination settings.

readonly attribute boolean IMachineDebugger::HWVirtExEnabled

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

readonly attribute boolean IMachineDebugger::HWVirtExNestedPagingEnabled

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

readonly attribute boolean IMachineDebugger::HWVirtExVPIDEnabled

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

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.

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.

readonly attribute boolean IMachineDebugger::PAEEnabled

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

attribute unsigned long IMachineDebugger::virtualTimeRate

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

The accepted range is 2% to 20000%.

readonly attribute long long IMachineDebugger::VM

Gets the VM handle.

This is only for internal use while we carve the details of this interface.