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,[retval] 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 executeAllInIEM
 Whether to execute all the code in the instruction interpreter.
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 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 VM
 Gets the user-mode VM handle, with a reference.

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 parallel 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,
[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

attribute boolean IMachineDebugger::singleStep

Switch for enabling single-stepping.

Switch for forcing code recompilation for user mode code.

Switch for forcing code recompilation for supervisor mode code.

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.

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.

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 boolean IMachineDebugger::HWVirtExUXEnabled

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

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