Windows Hypervisor Platform Instruction Emulator API Definitions and Support DLLs
This API is available starting in the Windows April 2018 Update.
Instruction emulation expects several higher-level abstractions at the interface between the accelerators and the device emulation that are not provided directly by the platform APIs. This functionality is provided by a separate DLL that builds these abstractions on top of the platform APIs.
Instruction Emulation
Device emulation expects the platform to provide the details of an I/O access by a virtual processor. For an MMIO and string I/O port access this requires decoding and completing the instruction that issued the I/O access.
Structure | Description |
---|---|
MMIO Access | Instruction emulation expects this data for MMIO access |
I/O Port Access | Instruction emulation expects this data for port access |
Virtual Processor Register State
Instruction emulation uses a fixed set of registers that are queried and set together if necessary. For X64, this set of registers include:
- RAX...R15, RIP, RFLAGS
- CS, SS, DS, ES, FS, GS, LDT, TR, GDT, IDT
- CR0, CR2, CR3, CR4
- FPU:
- XMM0...15, FPMMX0...7
- FCW, FSW, FTW, FOP, FIP, FDP, MXCSR
- MSRs:
- SYSENTER_CS, SYSENTER_ESP, SYSENTER_EIP, TSC
- EFER, STAR, LSTAR, CSTAR, FMASK, KERNELGSBASE
This set of registers is provided using the WHvGetVirtualProcessorRegisters
and WHvSetVirtualProcessorRegisters
platform functions, keeping it in sync with the register state used by the instruction emulation.
Windows Hypervisor Platform Instruction Emulator API Reference
Emulator Structures
Structure | Description |
---|---|
WHV_EMULATOR_CALLBACKS |
Used in WHvEmulatorCreateEmulator to specify callback methods needed by the emulator. |
WHV_EMULATOR_STATUS |
Describes extended return status information from a given emulation call. |
WHV_EMULATOR_MEMORY_ACCESS_INFO |
Information about the requested memory access by the emulator |
WHV_EMULATOR_IO_ACCESS_INFO |
Information about the requested Io Port access by the emulator |
API Methods
Methods | Description |
---|---|
WHvEmulatorCreateEmulator | Create an instance of the instruction emulator with the specified callback methods |
WHvEmulatorDestoryEmulator | Destroy an instance of the instruction emulator created by WHvEmulatorCreateEmulator |
WHvEmulatorTryIoEmulation and WHvEmulatorTryMmioEmulation | Attempt to emulate a given type of instruction with the given instruction context returned by the WinHv APIs from a RunVirtualProcessor call. |
Callback Functions
Functions | Description |
---|---|
WHV_EMULATOR_IO_PORT_CALLBACK |
Callback notifying the virtualization stack that the current instruction has modified the IO Port specified in the IoAccess structure |
WHV_EMULATOR_MEMORY_CALLBACK |
Callback notifying the virtualization stack that the current instruction is attempting to accessing memory as specified in the MemoryAccess structure. |
WHV_EMULATOR_GET_VIRTUAL_PROCESSOR_REGISTERS_CALLBACK |
Callback requesting VP register state, similar to the WinHv API |
WHV_EMULATOR_SET_VIRTUAL_PROCESSOR_REGISTERS_CALLBACK |
Callback setting VP register state, similar to the WinHv API |
WHV_EMULATOR_TRANSLATE_GVA_PAGE_CALLBACK |
Callback requesting the virtualization stack to translate the Guest Virtual Address GvaPage that points to the start of a 4K page, with the specified TranslateFlags |
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for