Documentation/virtual/kvm/hypercalls.txt

   1 Linux KVM Hypercall:
   2 ===================
   3 X86:
   4  KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall
   5  instruction. The hypervisor can replace it with instructions that are
   6  guaranteed to be supported.
   7
   8  Up to four arguments may be passed in rbx, rcx, rdx, and rsi respectively.
   9  The hypercall number should be placed in rax and the return value will be
  10  placed in rax.  No other registers will be clobbered unless explicitly stated
  11  by the particular hypercall.
  12
  13 S390:
  14   R2-R7 are used for parameters 1-6. In addition, R1 is used for hypercall
  15   number. The return value is written to R2.
  16
  17   S390 uses diagnose instruction as hypercall (0x500) along with hypercall
  18   number in R1.
  19
  20   For further information on the S390 diagnose call as supported by KVM,
  21   refer to Documentation/virtual/kvm/s390-diag.txt.
  22
  23  PowerPC:
  24   It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers.
  25   Return value is placed in R3.
  26
  27   KVM hypercalls uses 4 byte opcode, that are patched with 'hypercall-instructions'
  28   property inside the device tree's /hypervisor node.
  29   For more information refer to Documentation/virtual/kvm/ppc-pv.txt
  30
  31 KVM Hypercalls Documentation
  32 ===========================
  33 The template for each hypercall is:
  34 1. Hypercall name.
  35 2. Architecture(s)
  36 3. Status (deprecated, obsolete, active)
  37 4. Purpose
  38
  39 1. KVM_HC_VAPIC_POLL_IRQ
  40 ------------------------
  41 Architecture: x86
  42 Status: active
  43 Purpose: Trigger guest exit so that the host can check for pending
  44 interrupts on reentry.
  45
  46 2. KVM_HC_MMU_OP
  47 ------------------------
  48 Architecture: x86
  49 Status: deprecated.
  50 Purpose: Support MMU operations such as writing to PTE,
  51 flushing TLB, release PT.
  52
  53 3. KVM_HC_FEATURES
  54 ------------------------
  55 Architecture: PPC
  56 Status: active
  57 Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
  58 used to enumerate which hypercalls are available. On PPC, either device tree
  59 based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration
  60 mechanism (which is this hypercall) can be used.
  61
  62 4. KVM_HC_PPC_MAP_MAGIC_PAGE
  63 ------------------------
  64 Architecture: PPC
  65 Status: active
  66 Purpose: To enable communication between the hypervisor and guest there is a
  67 shared page that contains parts of supervisor visible register state.
  68 The guest can map this shared page to access its supervisor register through
  69 memory using this hypercall.
  70
  71 5. KVM_HC_KICK_CPU
  72 ------------------------
  73 Architecture: x86
  74 Status: active
  75 Purpose: Hypercall used to wakeup a vcpu from HLT state
  76 Usage example : A vcpu of a paravirtualized guest that is busywaiting in guest
  77 kernel mode for an event to occur (ex: a spinlock to become available) can
  78 execute HLT instruction once it has busy-waited for more than a threshold
  79 time-interval. Execution of HLT instruction would cause the hypervisor to put
  80 the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the
  81 same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall,
  82 specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0)
  83 is used in the hypercall for future use.
  84
  85
  86 6. KVM_HC_CLOCK_PAIRING
  87 ------------------------
  88 Architecture: x86
  89 Status: active
  90 Purpose: Hypercall used to synchronize host and guest clocks.
  91 Usage:
  92
  93 a0: guest physical address where host copies
  94 "struct kvm_clock_offset" structure.
  95
  96 a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0)
  97 is supported (corresponding to the host's CLOCK_REALTIME clock).
  98
  99                 struct kvm_clock_pairing {
 100                         __s64 sec;
 101                         __s64 nsec;
 102                         __u64 tsc;
 103                         __u32 flags;
 104                         __u32 pad[9];
 105                 };
 106
 107        Where:
 108                * sec: seconds from clock_type clock.
 109                * nsec: nanoseconds from clock_type clock.
 110                * tsc: guest TSC value used to calculate sec/nsec pair
 111                * flags: flags, unused (0) at the moment.
 112
 113 The hypercall lets a guest compute a precise timestamp across
 114 host and guest.  The guest can use the returned TSC value to
 115 compute the CLOCK_REALTIME for its clock, at the same instant.
 116
 117 Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource,
 118 or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK.