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