0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===================
0004 Linux KVM Hypercall
0005 ===================
0006
0007 X86:
0008 KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall
0009 instruction. The hypervisor can replace it with instructions that are
0010 guaranteed to be supported.
0011
0012 Up to four arguments may be passed in rbx, rcx, rdx, and rsi respectively.
0013 The hypercall number should be placed in rax and the return value will be
0014 placed in rax. No other registers will be clobbered unless explicitly stated
0015 by the particular hypercall.
0016
0017 S390:
0018 R2-R7 are used for parameters 1-6. In addition, R1 is used for hypercall
0019 number. The return value is written to R2.
0020
0021 S390 uses diagnose instruction as hypercall (0x500) along with hypercall
0022 number in R1.
0023
0024 For further information on the S390 diagnose call as supported by KVM,
0025 refer to Documentation/virt/kvm/s390/s390-diag.rst.
0026
0027 PowerPC:
0028 It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers.
0029 Return value is placed in R3.
0030
0031 KVM hypercalls uses 4 byte opcode, that are patched with 'hypercall-instructions'
0032 property inside the device tree's /hypervisor node.
0033 For more information refer to Documentation/virt/kvm/ppc-pv.rst
0034
0035 MIPS:
0036 KVM hypercalls use the HYPCALL instruction with code 0 and the hypercall
0037 number in $2 (v0). Up to four arguments may be placed in $4-$7 (a0-a3) and
0038 the return value is placed in $2 (v0).
0039
0040 KVM Hypercalls Documentation
0041 ============================
0042
0043 The template for each hypercall is:
0044 1. Hypercall name.
0045 2. Architecture(s)
0046 3. Status (deprecated, obsolete, active)
0047 4. Purpose
0048
0049 1. KVM_HC_VAPIC_POLL_IRQ
0050 ------------------------
0051
0052 :Architecture: x86
0053 :Status: active
0054 :Purpose: Trigger guest exit so that the host can check for pending
0055 interrupts on reentry.
0056
0057 2. KVM_HC_MMU_OP
0058 ----------------
0059
0060 :Architecture: x86
0061 :Status: deprecated.
0062 :Purpose: Support MMU operations such as writing to PTE,
0063 flushing TLB, release PT.
0064
0065 3. KVM_HC_FEATURES
0066 ------------------
0067
0068 :Architecture: PPC
0069 :Status: active
0070 :Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
0071 used to enumerate which hypercalls are available. On PPC, either
0072 device tree based lookup ( which is also what EPAPR dictates)
0073 OR KVM specific enumeration mechanism (which is this hypercall)
0074 can be used.
0075
0076 4. KVM_HC_PPC_MAP_MAGIC_PAGE
0077 ----------------------------
0078
0079 :Architecture: PPC
0080 :Status: active
0081 :Purpose: To enable communication between the hypervisor and guest there is a
0082 shared page that contains parts of supervisor visible register state.
0083 The guest can map this shared page to access its supervisor register
0084 through memory using this hypercall.
0085
0086 5. KVM_HC_KICK_CPU
0087 ------------------
0088
0089 :Architecture: x86
0090 :Status: active
0091 :Purpose: Hypercall used to wakeup a vcpu from HLT state
0092 :Usage example:
0093 A vcpu of a paravirtualized guest that is busywaiting in guest
0094 kernel mode for an event to occur (ex: a spinlock to become available) can
0095 execute HLT instruction once it has busy-waited for more than a threshold
0096 time-interval. Execution of HLT instruction would cause the hypervisor to put
0097 the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the
0098 same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall,
0099 specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0)
0100 is used in the hypercall for future use.
0101
0102
0103 6. KVM_HC_CLOCK_PAIRING
0104 -----------------------
0105 :Architecture: x86
0106 :Status: active
0107 :Purpose: Hypercall used to synchronize host and guest clocks.
0108
0109 Usage:
0110
0111 a0: guest physical address where host copies
0112 "struct kvm_clock_offset" structure.
0113
0114 a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0)
0115 is supported (corresponding to the host's CLOCK_REALTIME clock).
0116
0117 ::
0118
0119 struct kvm_clock_pairing {
0120 __s64 sec;
0121 __s64 nsec;
0122 __u64 tsc;
0123 __u32 flags;
0124 __u32 pad[9];
0125 };
0126
0127 Where:
0128 * sec: seconds from clock_type clock.
0129 * nsec: nanoseconds from clock_type clock.
0130 * tsc: guest TSC value used to calculate sec/nsec pair
0131 * flags: flags, unused (0) at the moment.
0132
0133 The hypercall lets a guest compute a precise timestamp across
0134 host and guest. The guest can use the returned TSC value to
0135 compute the CLOCK_REALTIME for its clock, at the same instant.
0136
0137 Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource,
0138 or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK.
0139
0140 6. KVM_HC_SEND_IPI
0141 ------------------
0142
0143 :Architecture: x86
0144 :Status: active
0145 :Purpose: Send IPIs to multiple vCPUs.
0146
0147 - a0: lower part of the bitmap of destination APIC IDs
0148 - a1: higher part of the bitmap of destination APIC IDs
0149 - a2: the lowest APIC ID in bitmap
0150 - a3: APIC ICR
0151
0152 The hypercall lets a guest send multicast IPIs, with at most 128
0153 128 destinations per hypercall in 64-bit mode and 64 vCPUs per
0154 hypercall in 32-bit mode. The destinations are represented by a
0155 bitmap contained in the first two arguments (a0 and a1). Bit 0 of
0156 a0 corresponds to the APIC ID in the third argument (a2), bit 1
0157 corresponds to the APIC ID a2+1, and so on.
0158
0159 Returns the number of CPUs to which the IPIs were delivered successfully.
0160
0161 7. KVM_HC_SCHED_YIELD
0162 ---------------------
0163
0164 :Architecture: x86
0165 :Status: active
0166 :Purpose: Hypercall used to yield if the IPI target vCPU is preempted
0167
0168 a0: destination APIC ID
0169
0170 :Usage example: When sending a call-function IPI-many to vCPUs, yield if
0171 any of the IPI target vCPUs was preempted.
0172
0173 8. KVM_HC_MAP_GPA_RANGE
0174 -------------------------
0175 :Architecture: x86
0176 :Status: active
0177 :Purpose: Request KVM to map a GPA range with the specified attributes.
0178
0179 a0: the guest physical address of the start page
0180 a1: the number of (4kb) pages (must be contiguous in GPA space)
0181 a2: attributes
0182
0183 Where 'attributes' :
0184 * bits 3:0 - preferred page size encoding 0 = 4kb, 1 = 2mb, 2 = 1gb, etc...
0185 * bit 4 - plaintext = 0, encrypted = 1
0186 * bits 63:5 - reserved (must be zero)
0187
0188 **Implementation note**: this hypercall is implemented in userspace via
0189 the KVM_CAP_EXIT_HYPERCALL capability. Userspace must enable that capability
0190 before advertising KVM_FEATURE_HC_MAP_GPA_RANGE in the guest CPUID. In
0191 addition, if the guest supports KVM_FEATURE_MIGRATION_CONTROL, userspace
0192 must also set up an MSR filter to process writes to MSR_KVM_MIGRATION_CONTROL.
