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

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

Documentation/virt/kvm/hypercalls.txt→Documentation/virt/kvm/hypercalls.rst

+73 −56
Original line number Diff line number Diff line 
Linux KVM Hypercall:

.. SPDX-License-Identifier: GPL-2.0



===================

Linux KVM Hypercall

===================



X86:

 KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall

 instruction. The hypervisor can replace it with instructions that are
@@ -34,7 +38,8 @@ MIPS: 
  the return value is placed in $2 (v0).



KVM Hypercalls Documentation

===========================

============================



The template for each hypercall is:

1. Hypercall name.

2. Architecture(s)
@@ -43,42 +48,49 @@ The template for each hypercall is: 


1. KVM_HC_VAPIC_POLL_IRQ

------------------------

Architecture: x86

Status: active

Purpose: Trigger guest exit so that the host can check for pending



:Architecture: x86

:Status: active

:Purpose: Trigger guest exit so that the host can check for pending

          interrupts on reentry.



2. KVM_HC_MMU_OP

------------------------

Architecture: x86

Status: deprecated.

Purpose: Support MMU operations such as writing to PTE,

----------------



:Architecture: x86

:Status: deprecated.

:Purpose: Support MMU operations such as writing to PTE,

          flushing TLB, release PT.



3. KVM_HC_FEATURES

------------------------

Architecture: PPC

Status: active

Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid

used to enumerate which hypercalls are available. On PPC, either device tree

based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration

mechanism (which is this hypercall) can be used.

------------------



:Architecture: PPC

:Status: active

:Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid

          used to enumerate which hypercalls are available. On PPC, either

	  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

------------------------

Architecture: PPC

Status: active

Purpose: To enable communication between the hypervisor and guest there is a

----------------------------



:Architecture: PPC

:Status: active

:Purpose: To enable communication between the hypervisor and guest there is a

	  shared page that contains parts of supervisor visible register state.

The guest can map this shared page to access its supervisor register through

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

------------------------

Architecture: x86

Status: active

Purpose: Hypercall used to wakeup a vcpu from HLT state

Usage example : A vcpu of a paravirtualized guest that is busywaiting in guest

------------------



:Architecture: x86

:Status: active

:Purpose: Hypercall used to wakeup a vcpu from HLT state

:Usage example:

  A vcpu of a paravirtualized guest that is busywaiting in guest

  kernel mode for an event to occur (ex: a spinlock to become available) can

  execute HLT instruction once it has busy-waited for more than a threshold

  time-interval. Execution of HLT instruction would cause the hypervisor to put
@@ -89,10 +101,11 @@ is used in the hypercall for future use. 




6. KVM_HC_CLOCK_PAIRING

------------------------

Architecture: x86

Status: active

Purpose: Hypercall used to synchronize host and guest clocks.

-----------------------

:Architecture: x86

:Status: active

:Purpose: Hypercall used to synchronize host and guest clocks.



Usage:



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)

is supported (corresponding to the host's CLOCK_REALTIME clock).



       ::



		struct kvm_clock_pairing {

			__s64 sec;

			__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.



6. KVM_HC_SEND_IPI

------------------------

Architecture: x86

Status: active

Purpose: Send IPIs to multiple vCPUs.

------------------



:Architecture: x86

:Status: active

:Purpose: Send IPIs to multiple vCPUs.



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

- 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

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.



7. KVM_HC_SCHED_YIELD

------------------------

Architecture: x86

Status: active

Purpose: Hypercall used to yield if the IPI target vCPU is preempted

---------------------



:Architecture: x86

:Status: active

:Purpose: Hypercall used to yield if the IPI target vCPU is preempted



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.

Documentation/virt/kvm/index.rst

+2 −0
Original line number Diff line number Diff line
@@ -11,8 +11,10 @@ KVM 
   amd-memory-encryption

   cpuid

   halt-polling

   hypercalls

   msr

   vcpu-requests



   arm/index



   devices/index

CRA Git | Maintained and supported by SUSTech CRA and CCSE