Hypercall Input Values

Callers use a 64-bit hypercall input value to specify a hypercall. The fields that make up the hypercall input value are described in the following table. Callers use the HV_X64_HYPERCALL_INPUT union to encode a hypercall input value.

Field	Bit size	Meaning
Call code	16 bits	Specifies which hypercall is requested. The HV_CALL_CODE enumeration contains all hypercall codes. Hypercall Function Code Reference lists hypercall functions by each function's code number.
Fast	1 bit	Specifies whether the hypercall uses the register-based calling convention. If set to 0, the hypercall uses the memory-based calling convention. If set to 1, the hypercall uses the register-based calling convention. If the register-based calling convention is used, the Rep* fields must be zero.
RsvdZ	4 bits or 15 bits	Must be zero.
Rep count	12 bits	Total number of rep hypercalls (this field is for a rep hypercall, and must be zero for a simple hypercall).
Rep start index	12 bits	The starting rep hypercall index (this field is for a rep hypercall, and must be zero for a simple hypercall).

The following table shows the order of the bits in the hypercall input value.

Bits	63:60	59:48	47:44	43:32	31:17	16	15:0
Fields	RsvdZ (4 bits)	Rep start index (12 bits)	RsvdZ (4 bits)	Rep count (12 bits)	RsvdZ (15 bits)	Fast (1 bit)	Call code (16 bits)

Bits

63:60

59:48

47:44

43:32

31:17

15:0

Fields

RsvdZ

(4 bits)

Rep start index

(12 bits)

RsvdZ

(4 bits)

Rep count

(12 bits)

RsvdZ

(15 bits)

Fast

(1 bit)

Call code

(16 bits)

For rep hypercalls, the Rep count field indicates the total number of repetitions. The Rep start index field indicates the particular repetition in relation to the start of the list (zero indicates that the first element in the list is to be processed). Therefore, Rep count must always be greater than Rep start index.

Register Mapping with Fast Off

The following table represents the register mapping for hypercall input values when the Fast field is off (that is, set to 0).

x64 register	x86 register	Contents
RCX	EDX:EAX	Hypercall input value
RDX	EBX:ECX	GPA of input parameters
R8	EDI:ESI	GPA of output parameters

The hypercall input value is passed in registers together with a guest physical address (GPA) that points to the input and output parameters. The register mappings depend on whether the caller is running in 32-bit (x86) or 64-bit (x64) mode. The hypervisor determines the caller's mode based on the value of EFER.LMA and CS.L flags. If both flags are set, the caller is assumed to be a 64-bit caller.

Some register values are considered volatile and can be modified by a hypercall. Volatile registers include the condition code registers SF, ZF, OF, CF, AF, and PF. EAX, ECX, and EDX for x86 callers and RCX, RDX, R8, R9, R10, R11, and XMM0 through XMM5 for x64 callers are also considered volatile registers.

Hypercall always overwrites RAX (on x64-based operating systems) and EDX:EAX (on x86-based operating systems) with the hypercall output value.

Register Mapping with Fast On

The following table represents the register mapping for hypercall inputs when the Fast field is on (that is, set to 1).

x64 registers	x86 registers	Contents
RCX	EDX:EAX	Hypercall input value
RDX	EBX:ECX	First input parameter
R8	EDI:ESI	Second input parameter

The hypercall input value is passed in registers with the first and second input parameters. The register mappings depend on whether the caller is running in 32-bit (x86) or 64-bit (x64) mode. The hypervisor determines the caller's mode based on the value of EFER.LMA and CS.L flags. If both flags are set, hypervisor assumes that the caller is running in the64-bit mode.

Some register values are considered volatile and can be modified by a hypercall. Volatile registers include the condition code registers SF, ZF, OF, CF, AF, and PF. EAX, ECX, EDX, EDI, and ESI for x86 callers and RCX, RDX, R8, R9, R10, R11, and XMM0 through XMM5 for x64 callers are also considered volatile registers.

Hypercall always overwrites RAX, RDX, and R8 (on x64-based operating systems) and EDX:EAX, EBX:ECX, and EDI:ESI (on x86-based operating systems) with the hypercall output value.

Extended Fast Hypercalls

Version 2.0 and later versions of the hypervisor support the use of extended fast hypercalls, which allow some hypercalls to take advantage of the improved performance of the fast hypercall interface even though they require more than two input parameters. The extended fast hypercall interface uses six volatile XMM registers to allow the caller to pass an input parameter block up to 112 bytes in size. Availability of the extended fast hypercall interface is indicated by the presence of a flag that is returned by the CPUID instruction for a hypervisor leaf (for more information about hypervisor CPUID leaves, see Microsoft Hypervisor CPUID Leaves). Any attempt to use this interface when the hypervisor does not indicate availability will result in a #UD fault.

The following table represents the register mapping for extended fast hypercall inputs when the Fast field is on (that is, set to 1).

x64 registers	x86 registers	Contents
RCX	EDX:EAX	Hypercall input value
RDX	EBX:ECX	Input parameter block (byte 0-7)
R8	EDI:ESI	Input parameter block (byte 8-15)
XMM0	XMM0	Input parameter block (byte 16-31)
XMM1	XMM1	Input parameter block (byte 32-47)
XMM2	XMM2	Input parameter block (byte 48-63)
XMM3	XMM3	Input parameter block (byte 64-79)
XMM4	XMM4	Input parameter block (byte 80-95)
XMM5	XMM5	Input parameter block (byte 96-111)

The hypercall input value is passed in registers along with the input parameters. The register mappings depend on whether the caller is running in 32-bit (x86) or 64-bit (x64) mode. The hypervisor determines the caller's mode based on the value of EFER.LMA and CS.L. If both of these flags are set, the hypervisor determines that the caller is 64 bit. If the input parameter block is smaller than 112 bytes, any extra bytes in the registers are ignored.

Some register values are considered volatile and can be modified by a hypercall. This list includes the condition code registers SF, ZF, OF, CF, AF, and PF. It also includes EAX, ECX, EDX, EDI, and ESI for x86 callers and RCX, RDX, R8, R9, R10, R11, and XMM0 through XMM5 for x64 callers.

Hypercall always overwrites RAX, RDX, and R8 (on x64-based operating systems) and EDX:EAX, EBX:ECX, and EDI:ESI (on x86-based operating systems) with the hypercall output value.

Send comments about this topic to Microsoft

Build date: 11/16/2013