| VirtualBox Main API
    | 
 
 | 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. | |
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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::loadPlugIn | ( | in wstring | name, | 
| [retval] out wstring | plugInName | ||
| ) | 
Loads a DBGF plug-in.
| name | The plug-in name or DLL. Special name 'all' loads all installed plug-ins. | 
| plugInName | The name of the loaded plug-in. | 
| void IMachineDebugger::unloadPlugIn | ( | in wstring | name | ) | 
Unloads a DBGF plug-in.
| name | The plug-in name or DLL. Special name 'all' unloads all plug-ins. | 
| 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.
| os | The detected OS kernel on success. | 
| void IMachineDebugger::queryOSKernelLog | ( | in unsigned long | maxMessages, | 
| [retval] out wstring | dmesg | ||
| ) | 
Tries to get the kernel log (dmesg) of the guest OS.
| maxMessages | Max number of messages to return, counting from the end of the log. If 0, there is no limit. | 
| dmesg | The kernel log. | 
| void IMachineDebugger::getRegister | ( | in unsigned long | cpuId, | 
| in wstring | name, | ||
| [retval] out wstring | value | ||
| ) | 
Gets one register.
| 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.
| 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.
| 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.
| 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.
| cpuId | The identifier of the Virtual CPU. | 
| stack | String containing the formatted stack dump. | 
| void IMachineDebugger::resetStats | ( | in wstring | pattern | ) | 
Reset VM statistics.
| 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. | 
| void IMachineDebugger::dumpStats | ( | in wstring | pattern | ) | 
Dumps VM statistics.
| 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. | 
| void IMachineDebugger::getStats | ( | in wstring | pattern, | 
| in boolean | withDescriptions, | ||
| [retval] out wstring | stats | ||
| ) | 
Get the VM statistics in a XMLish format.
| 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. | 
| 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.
| 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 | 
| 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.
| 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. | 
| 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.
| 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. | 
| attribute boolean IMachineDebugger::singleStep | 
Switch for enabling single-stepping.
| 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.
| 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 VMExecutionEngine IMachineDebugger::executionEngine | 
Gets the main execution engine of the VM.
| 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 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::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.