User:DoULikeIce/sandbox

Windows Hypervisor Platform

This article refers to a set of APIs used to enhance Windows virtualization. For other uses, see WHP (Disambiguation).

The Windows Hypervisor Platform (WHP) is a set of application programming interfaces (APIs) provided by Microsoft that enable third-party virtualization stacks and applications to create and manage partitions at the hypervisor level. These APIs allow software to configure memory mappings, manage virtual processor execution, and control access to virtual machine (VM) resources.

History and functionality

This platform was announced available to users after installing the Windows 10, April 2018 update, released on April 30th of 2018. The platform co-exists with Hyper-V or other third-party virtualization software and allows assistance in running other Hyper-V based features. The Windows Hypervisor Platform, when creating a virtual machine (VM), it refers to the new integrated scheduler of the hypervisor. In order to run a virtual processor, or virtual machine, a thread in the process of the virtualization stack issues a blocking call to execute the virtual machine, or processor, in the hypervisor. The call returns because of an operation of the virtual processor which requires handling in the virtualization stack or because of a request by the stack itself.

Thread execution

The directed thread that handles a virtual processor executes these operations to maintain stability and successful operation in the virtual machine:

• Create the virtual processor in the partition.
• Set up the state of the virtual processor, which includes injecting pending interrupts and events into the processor.
• Run the virtual processor.
• Upon return from running the virtual processor, query the state of the processor and handle the operation that caused the processor to stop running.
• If the virtual processor is still active, it will retreat to the second step and continue to run the processor.
• Delete the virtual processor in the partition.

The thread has many functions to execute these virtual processor-specific operations, listed in the table below.

The following table is quite large as it lists several thread execution functions and descriptions, you may or may not have to read the following.

Execution Table

Thread functions to run a virtual processor and allocate resources carefully

Function	Description
WHvCreateVirtualProcessor	This function creates a new virtual processor in a partition. The index of the virtual processor is used to set the APIC ID of the processor.
WHvDeleteVirtualProcessor	This function deletes a virtual processor in a partition.
WHvRunVirtualProcessor	This function executes the virtual processor (i.e., enables to run guest code). A call to this function blocks synchronously until either the virtual processor executed an operation that needs to be handled by the virtualization stack (e.g., accessed memory in the GPA space that is not mapped or not accessible) or the virtualization stack explicitly request an exit of the function (e.g., to inject an interrupt for the virtual processor or to change the state of the VM).
WHvCancelVirtualProcessor	Canceling the execution of a virtual processor allows an application to abort the call to run the virtual processor by another thread, and to return the control to that thread. The virtualization stack can use this function to return the control of a virtual processor back to the virtualization stack in case it needs to change the state of a VM or to inject an event into the processor.
WHvMapGpaRange	Creating a mapping for a range in the GPA space of a partition sets a region in the caller’s process as the backing memory for that range. The operation replaces any previous mappings for the specified GPA pages.
WHvUnmapGpaRange	Unmapping a previously mapped GPA range makes the memory range unavailable to the partition. Any further access by a virtual processor to the range will result in a memory access exit.
WHvTranslateGva	Translating a virtual address used by a virtual processor in a partition allows the virtualization stack to emulate a processor instruction for an I/O operation, using the results of the translation to read and write the memory operands of the instruction in the GPA space of the partition.
WHvQueryGpaRangeDirtyBitmap	Querying a range of GPA space to determine which pages have been modified by the guest since the last query of the range.
WHvCreatePartition	Creating a partition creates a new partition object. Additional properties of the partition are stored in the partition object and are applied when creating the partition in the hypervisor.
WHvSetupPartition	Setting up the partition causes the actual partition to be created in the hypervisor. A partition needs to be set up prior to performing any other operation on the partition after it was created, with exception of configuring the initial properties of the partition.
WHvDeletePartition	Deleting a partition tears down the partition object and releases all resources that the partition was using.
WHvGetPartitionProperty	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.
WHvSetPartitionProperty	This function sets the configurations of partition properties.
WHvGetVirtualProcessRegisters	This function allows for querying a set of individual registers by the virtualization stack.
WHvGetVirtualProcessorXsaveState	This function allows for querying a virtual processor's XSAVE state.
WHvSetVirtualProcessorRegisters	This function allows for setting a set of individual registers by the virtualization stack.
WHvSetVirtualProcessorXsaveState	This function allows for setting a virtual processor's XSAVE state.

One function is excluded due to irrelevancy, read the following to find out:

WHvGetCapability

Platform capabilities are a generic way for callers to query properties and capabilities of the hypervisor, of the API implementation, and of the hardware platform that the application is running on. The platform API uses these capabilities to publish the availability of extended functionality of the API as well as the set of features that the processor on the current system supports.

Major Updates and compatibility

Since the April 2018 update of Windows 10, the Windows Hypervisor Platform continues to expand with new considerations in its development.

Compatibility

As for architectures ARM64 and x64, Microsoft supports both as demonstrations on the GitHub repositories corresponding to both versions, programmed in CPP ^ARM64x64, but both are also supported via the Optional Features executable on Windows through optionalfeatures.exe > Windows Hypervisor Platform (ON/OFF).

Major Updates and Development

[UNFINISHED, WIP]