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

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

dumpStats()

void IMachineDebugger::dumpStats

(

in wstring

pattern

)

Dumps VM statistics.

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.

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.

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

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.

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.