Establishing the Hypercall Interface

Callers use a special opcode to make hypercalls. Because this opcode differs among virtualization implementations, the hypervisor must abstract this difference. The hypervisor abstracts opcode differences through a special hypercall page. The hypercall page is provided by the hypervisor and is located in the guest operating system's guest physical address (GPA) space. The guest operating system must program the following MSR to specify the location of the hypercall page:

#define HV_X64_MSR_HYPERCALL 0x40000001

The following table describes the fields of the opcode.

The following table shows the order of the bits in the opcode.

The guest operating system uses a HV_X64_MSR_HYPERCALL_CONTENTS union to program a hypercall page set up MSR.

The hypervisor can put the hypercall page anywhere within the guest operating system's GPA space, but the page must be page-aligned. If the guest operating system tries to move the hypercall page beyond the bounds of the GPA space, a #GP fault will result when the MSR is written.

This MSR is a partition-wide MSR. In other words, it is shared by all virtual processors in the partition. If one virtual processor successfully writes to the MSR, another virtual processor will read the same value.

Before the hypercall page is enabled, the guest operating system must report the operating system's identity by writing its version signature to a separate MSR (HV_X64_MSR_GUEST_OS_ID). If no guest operating system identity has been specified, attempts to enable the hypercall will fail. The enable bit will remain zero even if a 1 is written to it. Additionally, if the guest operating system identity is cleared to zero after the hypercall page has been enabled, the hypercall page will become disabled.

The hypercall page appears as an overlay to the GPA space. That is, the hypercall page includes everything else that is mapped to the GPA range. The guest operating system can read and execute the contents of the hypercall page. If the operating system tries to write to the hypercall page, the hypervisor will issue a protection (#GP) exception.

After the hypercall page has been enabled, the operating system can make a hypercall by calling to the start of the hypercall page.

The following steps establish the hypercall page:

1. The guest operating system reads CPUID leaf 1 and determines whether a hypervisor is present by checking bit 31 of register ECX.

2. The guest operating system reads CPUID leaf 0x40000000 to determine the maximum hypervisor CPUID leaf (returned in register EAX) and CPUID leaf 0x40000001 to determine the interface signature (returned in register EAX). The guest verifies that the maximum leaf value is at least 0x40000005 and that the interface signature is equal to "Hv#1". This signature implies that the HV_X64_MSR_GUEST_OS_ID, HV_X64_MSR_HYPERCALL, and HV_X64_MSR_VP_INDEX registers are implemented.

3. The guest operating system writes its identity into the MSR HV_X64_MSR_GUEST_OS_ID if HV_X64_MSR_GUEST_OS_ID is zero.

4. The guest operating system reads the hypercall MSR (HV_X64_MSR_HYPERCALL).

5. The guest operating system checks the Enable Hypercall Page bit. If the bit is set, the hypercall interface is already active, and steps 6 and 7 should be omitted.

6. The guest operating system finds a page within its GPA space, preferably one that is not occupied by RAM, MMIO, and so on. If the page is occupied, the guest should avoid using it.

7. The guest operating system writes a new value to the hypercall MSR (HV_X64_MSR_HYPERCALL) that includes the GPA from step 6 and sets the Enable Hypercall Page bit to enable the interface.

8. The guest operating system creates an executable virtual address (VA) mapping to the hypercall page GPA.

9. The guest operating system consults CPUID leaf 0x40000003 to determine which hypervisor facilities it can use.

After the guest operating system establishes the hypercall interface, the guest can initiate a hypercall. To do this, the guest populates the registers per the hypercall protocol and issues a call to the beginning of the hypercall page. The hypercall page performs the equivalent of a near ret (0xC3) to return to the caller. Therefore, the hypercall must be invoked by using a valid stack.

Send comments about this topic to Microsoft

Build date: 11/16/2013