1.. SPDX-License-Identifier: GPL-2.0 2 3=================== 4Linux KVM Hypercall 5=================== 6 7X86: 8 KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall 9 instruction. The hypervisor can replace it with instructions that are 10 guaranteed to be supported. 11 12 Up to four arguments may be passed in rbx, rcx, rdx, and rsi respectively. 13 The hypercall number should be placed in rax and the return value will be 14 placed in rax. No other registers will be clobbered unless explicitly stated 15 by the particular hypercall. 16 17S390: 18 R2-R7 are used for parameters 1-6. In addition, R1 is used for hypercall 19 number. The return value is written to R2. 20 21 S390 uses diagnose instruction as hypercall (0x500) along with hypercall 22 number in R1. 23 24 For further information on the S390 diagnose call as supported by KVM, 25 refer to Documentation/virt/kvm/s390/s390-diag.rst. 26 27PowerPC: 28 It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers. 29 Return value is placed in R3. 30 31 KVM hypercalls uses 4 byte opcode, that are patched with 'hypercall-instructions' 32 property inside the device tree's /hypervisor node. 33 For more information refer to Documentation/virt/kvm/ppc-pv.rst 34 35MIPS: 36 KVM hypercalls use the HYPCALL instruction with code 0 and the hypercall 37 number in $2 (v0). Up to four arguments may be placed in $4-$7 (a0-a3) and 38 the return value is placed in $2 (v0). 39 40KVM Hypercalls Documentation 41============================ 42 43The template for each hypercall is: 441. Hypercall name. 452. Architecture(s) 463. Status (deprecated, obsolete, active) 474. Purpose 48 491. KVM_HC_VAPIC_POLL_IRQ 50------------------------ 51 52:Architecture: x86 53:Status: active 54:Purpose: Trigger guest exit so that the host can check for pending 55 interrupts on reentry. 56 572. KVM_HC_MMU_OP 58---------------- 59 60:Architecture: x86 61:Status: deprecated. 62:Purpose: Support MMU operations such as writing to PTE, 63 flushing TLB, release PT. 64 653. KVM_HC_FEATURES 66------------------ 67 68:Architecture: PPC 69:Status: active 70:Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid 71 used to enumerate which hypercalls are available. On PPC, either 72 device tree based lookup ( which is also what EPAPR dictates) 73 OR KVM specific enumeration mechanism (which is this hypercall) 74 can be used. 75 764. KVM_HC_PPC_MAP_MAGIC_PAGE 77---------------------------- 78 79:Architecture: PPC 80:Status: active 81:Purpose: To enable communication between the hypervisor and guest there is a 82 shared page that contains parts of supervisor visible register state. 83 The guest can map this shared page to access its supervisor register 84 through memory using this hypercall. 85 865. KVM_HC_KICK_CPU 87------------------ 88 89:Architecture: x86 90:Status: active 91:Purpose: Hypercall used to wakeup a vcpu from HLT state 92:Usage example: 93 A vcpu of a paravirtualized guest that is busywaiting in guest 94 kernel mode for an event to occur (ex: a spinlock to become available) can 95 execute HLT instruction once it has busy-waited for more than a threshold 96 time-interval. Execution of HLT instruction would cause the hypervisor to put 97 the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the 98 same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall, 99 specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0) 100 is used in the hypercall for future use. 101 102 1036. KVM_HC_CLOCK_PAIRING 104----------------------- 105:Architecture: x86 106:Status: active 107:Purpose: Hypercall used to synchronize host and guest clocks. 108 109Usage: 110 111a0: guest physical address where host copies 112"struct kvm_clock_offset" structure. 113 114a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0) 115is supported (corresponding to the host's CLOCK_REALTIME clock). 116 117 :: 118 119 struct kvm_clock_pairing { 120 __s64 sec; 121 __s64 nsec; 122 __u64 tsc; 123 __u32 flags; 124 __u32 pad[9]; 125 }; 126 127 Where: 128 * sec: seconds from clock_type clock. 129 * nsec: nanoseconds from clock_type clock. 130 * tsc: guest TSC value used to calculate sec/nsec pair 131 * flags: flags, unused (0) at the moment. 132 133The hypercall lets a guest compute a precise timestamp across 134host and guest. The guest can use the returned TSC value to 135compute the CLOCK_REALTIME for its clock, at the same instant. 136 137Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource, 138or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK. 139 1406. KVM_HC_SEND_IPI 141------------------ 142 143:Architecture: x86 144:Status: active 145:Purpose: Send IPIs to multiple vCPUs. 146 147- a0: lower part of the bitmap of destination APIC IDs 148- a1: higher part of the bitmap of destination APIC IDs 149- a2: the lowest APIC ID in bitmap 150- a3: APIC ICR 151 152The hypercall lets a guest send multicast IPIs, with at most 128 153128 destinations per hypercall in 64-bit mode and 64 vCPUs per 154hypercall in 32-bit mode. The destinations are represented by a 155bitmap contained in the first two arguments (a0 and a1). Bit 0 of 156a0 corresponds to the APIC ID in the third argument (a2), bit 1 157corresponds to the APIC ID a2+1, and so on. 158 159Returns the number of CPUs to which the IPIs were delivered successfully. 160 1617. KVM_HC_SCHED_YIELD 162--------------------- 163 164:Architecture: x86 165:Status: active 166:Purpose: Hypercall used to yield if the IPI target vCPU is preempted 167 168a0: destination APIC ID 169 170:Usage example: When sending a call-function IPI-many to vCPUs, yield if 171 any of the IPI target vCPUs was preempted. 172 1738. KVM_HC_MAP_GPA_RANGE 174------------------------- 175:Architecture: x86 176:Status: active 177:Purpose: Request KVM to map a GPA range with the specified attributes. 178 179a0: the guest physical address of the start page 180a1: the number of (4kb) pages (must be contiguous in GPA space) 181a2: attributes 182 183 Where 'attributes' : 184 * bits 3:0 - preferred page size encoding 0 = 4kb, 1 = 2mb, 2 = 1gb, etc... 185 * bit 4 - plaintext = 0, encrypted = 1 186 * bits 63:5 - reserved (must be zero) 187 188**Implementation note**: this hypercall is implemented in userspace via 189the KVM_CAP_EXIT_HYPERCALL capability. Userspace must enable that capability 190before advertising KVM_FEATURE_HC_MAP_GPA_RANGE in the guest CPUID. In 191addition, if the guest supports KVM_FEATURE_MIGRATION_CONTROL, userspace 192must also set up an MSR filter to process writes to MSR_KVM_MIGRATION_CONTROL. 193