mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-09-13 22:25:03 +00:00
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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
This commit is contained in:
parent
cec0e48be3
commit
5a0af4806c
2 changed files with 75 additions and 56 deletions
|
@ -1,5 +1,9 @@
|
||||||
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:
|
||||||
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:
|
||||||
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:
|
||||||
|
|
||||||
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
|
||||||
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,
|
||||||
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
|
|
||||||
Purpose: Send IPIs to multiple vCPUs.
|
|
||||||
|
|
||||||
a0: lower part of the bitmap of destination APIC IDs
|
:Architecture: x86
|
||||||
a1: higher part of the bitmap of destination APIC IDs
|
:Status: active
|
||||||
a2: the lowest APIC ID in bitmap
|
:Purpose: Send IPIs to multiple vCPUs.
|
||||||
a3: APIC ICR
|
|
||||||
|
- a0: lower 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
|
||||||
|
- 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.
|
||||||
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
|
||||||
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
|
||||||
|
|
Loading…
Reference in a new issue