Documentation/virt/kvm/x86/hypercalls.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===================
   4 Linux KVM Hypercall
   5 ===================
   6
   7 X86:
   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
  17 S390:
  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
  27 PowerPC:
  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
  35 MIPS:
  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
  40 KVM Hypercalls Documentation
  41 ============================
  42
  43 The template for each hypercall is:
  44 1. Hypercall name.
  45 2. Architecture(s)
  46 3. Status (deprecated, obsolete, active)
  47 4. Purpose
  48
  49 1. 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
  57 2. 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
  65 3. 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
  76 4. 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
  86 5. 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
 103 6. KVM_HC_CLOCK_PAIRING
 104 -----------------------
 105 :Architecture: x86
 106 :Status: active
 107 :Purpose: Hypercall used to synchronize host and guest clocks.
 108
 109 Usage:
 110
 111 a0: guest physical address where host copies
 112 "struct kvm_clock_offset" structure.
 113
 114 a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0)
 115 is 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
 133 The hypercall lets a guest compute a precise timestamp across
 134 host and guest.  The guest can use the returned TSC value to
 135 compute the CLOCK_REALTIME for its clock, at the same instant.
 136
 137 Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource,
 138 or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK.
 139
 140 6. 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
 152 The hypercall lets a guest send multicast IPIs, with at most 128
 153 128 destinations per hypercall in 64-bit mode and 64 vCPUs per
 154 hypercall in 32-bit mode.  The destinations are represented by a
 155 bitmap contained in the first two arguments (a0 and a1). Bit 0 of
 156 a0 corresponds to the APIC ID in the third argument (a2), bit 1
 157 corresponds to the APIC ID a2+1, and so on.
 158
 159 Returns the number of CPUs to which the IPIs were delivered successfully.
 160
 161 7. 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
 168 a0: 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
 173 8. 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
 179 a0: the guest physical address of the start page
 180 a1: the number of (4kb) pages (must be contiguous in GPA space)
 181 a2: 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
 189 the KVM_CAP_EXIT_HYPERCALL capability. Userspace must enable that capability
 190 before advertising KVM_FEATURE_HC_MAP_GPA_RANGE in the guest CPUID.  In
 191 addition, if the guest supports KVM_FEATURE_MIGRATION_CONTROL, userspace
 192 must also set up an MSR filter to process writes to MSR_KVM_MIGRATION_CONTROL.