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