VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IPlatformX86 Interface Reference

The x86 specific platform properties for a virtual machine. More...

Inheritance diagram for IPlatformX86:

## Public Member Functions
void | getCPUProperty (in CPUPropertyTypeX86 property, [retval] out boolean value)
| Returns the virtual CPU boolean value of the specified property.
void | setCPUProperty (in CPUPropertyTypeX86 property, in boolean value)
| Sets the virtual CPU boolean value of the specified property.
void | getCPUIDLeafByOrdinal (in unsigned long ordinal, out unsigned long idx, out unsigned long idxSub, out unsigned long valEax, out unsigned long valEbx, out unsigned long valEcx, out unsigned long valEdx)
| Used to enumerate CPUID information override values.
void | getCPUIDLeaf (in unsigned long idx, in unsigned long idxSub, out unsigned long valEax, out unsigned long valEbx, out unsigned long valEcx, out unsigned long valEdx)
| Returns the virtual CPU cpuid information for the specified leaf.
void | setCPUIDLeaf (in unsigned long idx, in unsigned long idxSub, in unsigned long valEax, in unsigned long valEbx, in unsigned long valEcx, in unsigned long valEdx)
| Sets the virtual CPU cpuid information for the specified leaf.
void | removeCPUIDLeaf (in unsigned long idx, in unsigned long idxSub)
| Removes the virtual CPU cpuid leaf for the specified index.
void | removeAllCPUIDLeaves ()
| Removes all the virtual CPU cpuid leaves.
void | getHWVirtExProperty (in HWVirtExPropertyType property, [retval] out boolean value)
| Returns the value of the specified hardware virtualization boolean property.
void | setHWVirtExProperty (in HWVirtExPropertyType property, in boolean value)
| Sets a new value for the specified hardware virtualization boolean property.

## Public Attributes
attribute boolean | HPETEnabled
| This attribute controls if High Precision Event Timer (HPET) is enabled in this VM.

## Detailed Description

The x86 specific platform properties for a virtual machine.

Accessed via IMachine::platform and IPlatform::x86.

Interface ID:
  `{5ADA589F-09C9-4604-B700-9AB3A5572E3A}`

## Member Function Documentation

## ◆ getCPUProperty()

void IPlatformX86::getCPUProperty | ( | in CPUPropertyTypeX86 | property,
|  | [retval] out boolean | value
| ) |  |

Returns the virtual CPU boolean value of the specified property.

Parameters

  property | Property type to query.
  value | Property value.

Expected result codes:

  E_INVALIDARG | Invalid property.

## ◆ setCPUProperty()

void IPlatformX86::setCPUProperty | ( | in CPUPropertyTypeX86 | property,
|  | in boolean | value
| ) |  |

Sets the virtual CPU boolean value of the specified property.

Parameters

  property | Property type to query.
  value | Property value.

Expected result codes:

  E_INVALIDARG | Invalid property.

## ◆ getCPUIDLeafByOrdinal()

void IPlatformX86::getCPUIDLeafByOrdinal | ( | in unsigned long | ordinal,
|  | out unsigned long | idx,
|  | out unsigned long | idxSub,
|  | out unsigned long | valEax,
|  | out unsigned long | valEbx,
|  | out unsigned long | valEcx,
|  | out unsigned long | valEdx
| ) |  |

Used to enumerate CPUID information override values.

Parameters

  ordinal | The ordinal number of the leaf to get.
  idx | CPUID leaf index.
  idxSub | CPUID leaf sub-index.
  valEax | CPUID leaf value for register eax.
  valEbx | CPUID leaf value for register ebx.
  valEcx | CPUID leaf value for register ecx.
  valEdx | CPUID leaf value for register edx.

Expected result codes:

  E_INVALIDARG | Invalid ordinal number is out of range.

## ◆ getCPUIDLeaf()

void IPlatformX86::getCPUIDLeaf | ( | in unsigned long | idx,
|  | in unsigned long | idxSub,
|  | out unsigned long | valEax,
|  | out unsigned long | valEbx,
|  | out unsigned long | valEcx,
|  | out unsigned long | valEdx
| ) |  |

Returns the virtual CPU cpuid information for the specified leaf.

Currently supported index values for cpuid: Standard CPUID leaves: 0 - 0x1f Extended CPUID leaves: 0x80000000 - 0x8000001f VIA CPUID leaves: 0xc0000000 - 0xc000000f

See the Intel, AMD and VIA programmer's manuals for detailed information about the CPUID instruction and its leaves.

Parameters

  idx | CPUID leaf index.
  idxSub | CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable.
  valEax | CPUID leaf value for register eax.
  valEbx | CPUID leaf value for register ebx.
  valEcx | CPUID leaf value for register ecx.
  valEdx | CPUID leaf value for register edx.

Expected result codes:

  E_INVALIDARG | Invalid index.

## ◆ setCPUIDLeaf()

void IPlatformX86::setCPUIDLeaf | ( | in unsigned long | idx,
|  | in unsigned long | idxSub,
|  | in unsigned long | valEax,
|  | in unsigned long | valEbx,
|  | in unsigned long | valEcx,
|  | in unsigned long | valEdx
| ) |  |

Sets the virtual CPU cpuid information for the specified leaf.

Note that these values are not passed unmodified. VirtualBox clears features that it doesn't support.

Currently supported index values for cpuid: Standard CPUID leaves: 0 - 0x1f Extended CPUID leaves: 0x80000000 - 0x8000001f VIA CPUID leaves: 0xc0000000 - 0xc000000f

The subleaf index is only applicable to certain leaves (see manuals as this is subject to change).

See the Intel, AMD and VIA programmer's manuals for detailed information about the cpuid instruction and its leaves.

Do not use this method unless you know exactly what you're doing. Misuse can lead to random crashes inside VMs.

Parameters

  idx | CPUID leaf index.
  idxSub | CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable. The 0xffffffff causes it to remove all other subleaves before adding one with sub-index 0.
  valEax | CPUID leaf value for register eax.
  valEbx | CPUID leaf value for register ebx.
  valEcx | CPUID leaf value for register ecx.
  valEdx | CPUID leaf value for register edx.

Expected result codes:

  E_INVALIDARG | Invalid index.

## ◆ removeCPUIDLeaf()

void IPlatformX86::removeCPUIDLeaf | ( | in unsigned long | idx,
|  | in unsigned long | idxSub
| ) |  |

Removes the virtual CPU cpuid leaf for the specified index.

Parameters

  idx | CPUID leaf index.
  idxSub | CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable. The 0xffffffff value works like a wildcard.

Expected result codes:

  E_INVALIDARG | Invalid index.

## ◆ removeAllCPUIDLeaves()

void IPlatformX86::removeAllCPUIDLeaves | ( |  | ) |

Removes all the virtual CPU cpuid leaves.

## ◆ getHWVirtExProperty()

void IPlatformX86::getHWVirtExProperty | ( | in HWVirtExPropertyType | property,
|  | [retval] out boolean | value
| ) |  |

Returns the value of the specified hardware virtualization boolean property.

Parameters

  property | Property type to query.
  value | Property value.

Expected result codes:

  E_INVALIDARG | Invalid property.

## ◆ setHWVirtExProperty()

void IPlatformX86::setHWVirtExProperty | ( | in HWVirtExPropertyType | property,
|  | in boolean | value
| ) |  |

Sets a new value for the specified hardware virtualization boolean property.

Parameters

  property | Property type to set.
  value | New property value.

Expected result codes:

  E_INVALIDARG | Invalid property.

## Member Data Documentation

## ◆ HPETEnabled

attribute boolean IPlatformX86::HPETEnabled

This attribute controls if High Precision Event Timer (HPET) is enabled in this VM.

Use this property if you want to provide guests with additional time source, or if guest requires HPET to function correctly. Default is false.