Commit 5a0af480 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Paolo Bonzini

docs: kvm: Convert hypercalls.txt to ReST format

- Use document title and chapter markups;
- Convert tables;
- Add markups for literal blocks;
- use :field: for field descriptions;
- Add blank lines and adjust indentation
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarPaolo Bonzini <pbonzini@redhat.com>
parent cec0e48b
Linux KVM Hypercall: .. SPDX-License-Identifier: GPL-2.0
===================
Linux KVM Hypercall
=================== ===================
X86: X86:
KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall
instruction. The hypervisor can replace it with instructions that are instruction. The hypervisor can replace it with instructions that are
...@@ -20,7 +24,7 @@ S390: ...@@ -20,7 +24,7 @@ S390:
For further information on the S390 diagnose call as supported by KVM, For further information on the S390 diagnose call as supported by KVM,
refer to Documentation/virt/kvm/s390-diag.txt. refer to Documentation/virt/kvm/s390-diag.txt.
PowerPC: PowerPC:
It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers. It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers.
Return value is placed in R3. Return value is placed in R3.
...@@ -34,7 +38,8 @@ MIPS: ...@@ -34,7 +38,8 @@ MIPS:
the return value is placed in $2 (v0). the return value is placed in $2 (v0).
KVM Hypercalls Documentation KVM Hypercalls Documentation
=========================== ============================
The template for each hypercall is: The template for each hypercall is:
1. Hypercall name. 1. Hypercall name.
2. Architecture(s) 2. Architecture(s)
...@@ -43,56 +48,64 @@ The template for each hypercall is: ...@@ -43,56 +48,64 @@ The template for each hypercall is:
1. KVM_HC_VAPIC_POLL_IRQ 1. KVM_HC_VAPIC_POLL_IRQ
------------------------ ------------------------
Architecture: x86
Status: active :Architecture: x86
Purpose: Trigger guest exit so that the host can check for pending :Status: active
interrupts on reentry. :Purpose: Trigger guest exit so that the host can check for pending
interrupts on reentry.
2. KVM_HC_MMU_OP 2. KVM_HC_MMU_OP
------------------------ ----------------
Architecture: x86
Status: deprecated. :Architecture: x86
Purpose: Support MMU operations such as writing to PTE, :Status: deprecated.
flushing TLB, release PT. :Purpose: Support MMU operations such as writing to PTE,
flushing TLB, release PT.
3. KVM_HC_FEATURES 3. KVM_HC_FEATURES
------------------------ ------------------
Architecture: PPC
Status: active :Architecture: PPC
Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid :Status: active
used to enumerate which hypercalls are available. On PPC, either device tree :Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration used to enumerate which hypercalls are available. On PPC, either
mechanism (which is this hypercall) can be used. device tree based lookup ( which is also what EPAPR dictates)
OR KVM specific enumeration mechanism (which is this hypercall)
can be used.
4. KVM_HC_PPC_MAP_MAGIC_PAGE 4. KVM_HC_PPC_MAP_MAGIC_PAGE
------------------------ ----------------------------
Architecture: PPC
Status: active :Architecture: PPC
Purpose: To enable communication between the hypervisor and guest there is a :Status: active
shared page that contains parts of supervisor visible register state. :Purpose: To enable communication between the hypervisor and guest there is a
The guest can map this shared page to access its supervisor register through shared page that contains parts of supervisor visible register state.
memory using this hypercall. The guest can map this shared page to access its supervisor register
through memory using this hypercall.
5. KVM_HC_KICK_CPU 5. KVM_HC_KICK_CPU
------------------------ ------------------
Architecture: x86
Status: active :Architecture: x86
Purpose: Hypercall used to wakeup a vcpu from HLT state :Status: active
Usage example : A vcpu of a paravirtualized guest that is busywaiting in guest :Purpose: Hypercall used to wakeup a vcpu from HLT state
kernel mode for an event to occur (ex: a spinlock to become available) can :Usage example:
execute HLT instruction once it has busy-waited for more than a threshold A vcpu of a paravirtualized guest that is busywaiting in guest
time-interval. Execution of HLT instruction would cause the hypervisor to put kernel mode for an event to occur (ex: a spinlock to become available) can
the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the execute HLT instruction once it has busy-waited for more than a threshold
same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall, time-interval. Execution of HLT instruction would cause the hypervisor to put
specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0) the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the
is used in the hypercall for future use. same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall,
specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0)
is used in the hypercall for future use.
6. KVM_HC_CLOCK_PAIRING 6. KVM_HC_CLOCK_PAIRING
------------------------ -----------------------
Architecture: x86 :Architecture: x86
Status: active :Status: active
Purpose: Hypercall used to synchronize host and guest clocks. :Purpose: Hypercall used to synchronize host and guest clocks.
Usage: Usage:
a0: guest physical address where host copies a0: guest physical address where host copies
...@@ -101,6 +114,8 @@ a0: guest physical address where host copies ...@@ -101,6 +114,8 @@ a0: guest physical address where host copies
a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0) a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0)
is supported (corresponding to the host's CLOCK_REALTIME clock). is supported (corresponding to the host's CLOCK_REALTIME clock).
::
struct kvm_clock_pairing { struct kvm_clock_pairing {
__s64 sec; __s64 sec;
__s64 nsec; __s64 nsec;
...@@ -123,15 +138,16 @@ Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource, ...@@ -123,15 +138,16 @@ Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource,
or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK. or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK.
6. KVM_HC_SEND_IPI 6. KVM_HC_SEND_IPI
------------------------ ------------------
Architecture: x86
Status: active :Architecture: x86
Purpose: Send IPIs to multiple vCPUs. :Status: active
:Purpose: Send IPIs to multiple vCPUs.
a0: lower part of the bitmap of destination APIC IDs - a0: lower part of the bitmap of destination APIC IDs
a1: higher part of the bitmap of destination APIC IDs - a1: higher part of the bitmap of destination APIC IDs
a2: the lowest APIC ID in bitmap - a2: the lowest APIC ID in bitmap
a3: APIC ICR - a3: APIC ICR
The hypercall lets a guest send multicast IPIs, with at most 128 The hypercall lets a guest send multicast IPIs, with at most 128
128 destinations per hypercall in 64-bit mode and 64 vCPUs per 128 destinations per hypercall in 64-bit mode and 64 vCPUs per
...@@ -143,12 +159,13 @@ corresponds to the APIC ID a2+1, and so on. ...@@ -143,12 +159,13 @@ corresponds to the APIC ID a2+1, and so on.
Returns the number of CPUs to which the IPIs were delivered successfully. Returns the number of CPUs to which the IPIs were delivered successfully.
7. KVM_HC_SCHED_YIELD 7. KVM_HC_SCHED_YIELD
------------------------ ---------------------
Architecture: x86
Status: active :Architecture: x86
Purpose: Hypercall used to yield if the IPI target vCPU is preempted :Status: active
:Purpose: Hypercall used to yield if the IPI target vCPU is preempted
a0: destination APIC ID a0: destination APIC ID
Usage example: When sending a call-function IPI-many to vCPUs, yield if :Usage example: When sending a call-function IPI-many to vCPUs, yield if
any of the IPI target vCPUs was preempted. any of the IPI target vCPUs was preempted.
...@@ -11,8 +11,10 @@ KVM ...@@ -11,8 +11,10 @@ KVM
amd-memory-encryption amd-memory-encryption
cpuid cpuid
halt-polling halt-polling
hypercalls
msr msr
vcpu-requests vcpu-requests
arm/index arm/index
devices/index devices/index
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment