1Linux KVM Hypercall:
2===================
3X86:
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
13S390:
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
31MIPS:
32  KVM hypercalls use the HYPCALL instruction with code 0 and the hypercall
33  number in $2 (v0). Up to four arguments may be placed in $4-$7 (a0-a3) and
34  the return value is placed in $2 (v0).
35
36KVM Hypercalls Documentation
37===========================
38The template for each hypercall is:
391. Hypercall name.
402. Architecture(s)
413. Status (deprecated, obsolete, active)
424. Purpose
43
441. KVM_HC_VAPIC_POLL_IRQ
45------------------------
46Architecture: x86
47Status: active
48Purpose: Trigger guest exit so that the host can check for pending
49interrupts on reentry.
50
512. KVM_HC_MMU_OP
52------------------------
53Architecture: x86
54Status: deprecated.
55Purpose: Support MMU operations such as writing to PTE,
56flushing TLB, release PT.
57
583. KVM_HC_FEATURES
59------------------------
60Architecture: PPC
61Status: active
62Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
63used to enumerate which hypercalls are available. On PPC, either device tree
64based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration
65mechanism (which is this hypercall) can be used.
66
674. KVM_HC_PPC_MAP_MAGIC_PAGE
68------------------------
69Architecture: PPC
70Status: active
71Purpose: To enable communication between the hypervisor and guest there is a
72shared page that contains parts of supervisor visible register state.
73The guest can map this shared page to access its supervisor register through
74memory using this hypercall.
75
765. KVM_HC_KICK_CPU
77------------------------
78Architecture: x86
79Status: active
80Purpose: Hypercall used to wakeup a vcpu from HLT state
81Usage example : A vcpu of a paravirtualized guest that is busywaiting in guest
82kernel mode for an event to occur (ex: a spinlock to become available) can
83execute HLT instruction once it has busy-waited for more than a threshold
84time-interval. Execution of HLT instruction would cause the hypervisor to put
85the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the
86same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall,
87specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0)
88is used in the hypercall for future use.
89
90
916. KVM_HC_CLOCK_PAIRING
92------------------------
93Architecture: x86
94Status: active
95Purpose: Hypercall used to synchronize host and guest clocks.
96Usage:
97
98a0: guest physical address where host copies
99"struct kvm_clock_offset" structure.
100
101a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0)
102is supported (corresponding to the host's CLOCK_REALTIME clock).
103
104		struct kvm_clock_pairing {
105			__s64 sec;
106			__s64 nsec;
107			__u64 tsc;
108			__u32 flags;
109			__u32 pad[9];
110		};
111
112       Where:
113               * sec: seconds from clock_type clock.
114               * nsec: nanoseconds from clock_type clock.
115               * tsc: guest TSC value used to calculate sec/nsec pair
116               * flags: flags, unused (0) at the moment.
117
118The hypercall lets a guest compute a precise timestamp across
119host and guest.  The guest can use the returned TSC value to
120compute the CLOCK_REALTIME for its clock, at the same instant.
121
122Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource,
123or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK.
124
1256. KVM_HC_SEND_IPI
126------------------------
127Architecture: x86
128Status: active
129Purpose: Send IPIs to multiple vCPUs.
130
131a0: lower part of the bitmap of destination APIC IDs
132a1: higher part of the bitmap of destination APIC IDs
133a2: the lowest APIC ID in bitmap
134a3: APIC ICR
135
136The hypercall lets a guest send multicast IPIs, with at most 128
137128 destinations per hypercall in 64-bit mode and 64 vCPUs per
138hypercall in 32-bit mode.  The destinations are represented by a
139bitmap contained in the first two arguments (a0 and a1). Bit 0 of
140a0 corresponds to the APIC ID in the third argument (a2), bit 1
141corresponds to the APIC ID a2+1, and so on.
142
143Returns the number of CPUs to which the IPIs were delivered successfully.
144