Windows Hypervisor Platform API Definitions

This API is available starting in the Windows April 2018 Update.

The following diagram provides a high-level overview of the third-party architecture.

The following section contains the definitions of the Windows Hypervisor Platform APIs that are exposed through WinHvPlatform.h. WinHvPlatform.dll (located in the System32 folder) exports a set of C-style Windows API functions which return HRESULT error codes. The headers are published with the Windows SDK package.

Platform Capabilities

To determine whether the current system supports the Windows Hypervisor Platform on Arm64, call WHvGetCapability with WHvCapabilityCodeFeatures and test the Arm64Support bit of the returned WHV_CAPABILITY_FEATURES value.

Partition Creation, Setup, and Deletion

Partition Properties

Partition properties provide the mechanism for callers to query and configure the characteristics of a partition. Querying a property returns the current value of that property, which provides the default value determined by the hypervisor and API implementations in case the property hasn’t been previously modified by the caller. 

The availability of features that can be configured through the partition properties depends on the capabilities of the hypervisor, API implementation and the physical processor on the system. An application should check the corresponding capability before attempting to configure a property.

Several properties (for example, the properties that configure the processor features that are made available to the partition) can only be modified during the creation of the partition and prior to executing a virtual processor in the partition. An attempt to modify these properties after a partition started executing results in a failure of the operation.

For more information about the partition properties: Partition Property Data Types

Partition Reset and Migration

A partition can be reset to its initial state, and a running partition can be migrated from one host to another. Migration is a multi-step process that is started on the source host, accepted on the destination host, and then either completed or canceled on the source host.

VM Memory Management

The physical address space of the VM partition (the GPA space) is populated using memory allocated in the user-mode process of the virtualization stack. The virtualization stack allocates the required memory using standard Windows memory-management functions (such as VirtualAlloc), or maps a file into its process, and uses the addresses of these regions to map the memory into the partition’s GPA space.

For more information about the memory data types: Memory Data Types

Virtual Processor Execution

The virtual processors of a VM are executed using the new integrated scheduler of the hypervisor. To run a virtual processor, a thread in the virtualization-stack process issues a blocking call to execute the virtual processor in the hypervisor. The call returns when the virtual processor performs an operation that the virtualization stack must handle, or when the virtualization stack requests an exit.  

A thread that handles a virtual processor executes the following basic operations:

1. Create the virtual processor in the partition.
2. Setup the state of the virtual processor, which includes injecting pending interrupts and events into the processor.
3. Run the virtual processor.
4. Upon return from running the virtual processor, query the state of the processor and handle the operation that caused the processor to stop running.
5. If the virtual processor is still active, go back to Step 2 to continue to run the processor.
6. Delete the virtual processor in the partition.  

The state of the virtual processor includes the hardware registers and any interrupts the virtualization stack wants to inject into the virtual processor.

Exit Context

The detailed reason and additional information for the exit of the WHvRunVirtualProcessor function is returned in an output buffer of the function that receives a context structure for the exit. The data provided in this context buffer is specific to the individual exit reason, and for simple exit reasons the buffer might be unused (RunVpExitLegacyFpError and RunVpExitInvalidVpRegisterValue).

Virtual Processor Registers

The state of a virtual processor, which includes both the state defined by the underlying architecture (such as general-purpose registers) and additional state defined by the hypervisor, can be accessed through these functions.

For more information about the registers see: Virtual Processor Register Names and Values

Interrupt controller virtualization

Optionally, the hypervisor platform can emulate a local APIC interrupt controller. For virtual machines where an APIC is required, using the platform's built-in emulation yields the best performance. On Arm64, a partition must use the emulated interrupt controller (GIC), which is configured before the partition is set up. For more information, see WHvSetupPartition.

When this functionality is enabled, these functions can be used to request virtual interrupts and to query and set interrupt controller state.

Virtual Processor State

In addition to individual registers, the saved state of a virtual processor can be queried and set by category, and the CPUID results that a virtual processor observes can be queried.

Synthetic Interrupt Controller (SynIC)

These functions deliver synthetic interrupt controller (SynIC) events and messages to a virtual processor.

Counters

These functions can be used to query various hypervisor platform counters.

Doorbells

A doorbell allows the virtualization stack to be notified through a Windows event object when a guest writes a specified value to a specified guest physical address.

For more information about the doorbell data types: Doorbell Data Types

Triggers

A trigger delivers a pre-configured interrupt or event to a partition when a host event object is signaled.

For more information about the trigger data types: Trigger Data Types

Notification Ports

A notification port signals a Windows event object when a partition generates a matching event.

For more information about the notification port data types: Notification Port Data Types

Virtual PCI (VPCI) Devices

The Windows Hypervisor Platform can assign a physical PCI device to a partition as a virtual PCI (VPCI) device. These functions allocate the backing resources, create and delete VPCI devices, query their properties and notifications, map their MMIO ranges, manage their power state, and access their registers.

For more information about the VPCI data types: Virtual PCI Data Types

Virtual PCI (VPCI) Device Interrupts

These functions map, unmap, retarget, request, and query the MSI and MSI-X interrupts of an assigned virtual PCI device.