Linux KVM Hypercall

아키텍처별 호출 ABI

x86 hypervisor는 vmcall 또는 vmmcall sequence를 보장되는 다른 명령으로 patch할 수 있고, 각 하이퍼콜이 따로 명시하지 않는 한 다른 register는 clobber하지 않습니다. s390과 PowerPC의 상세 ABI는 각 아키텍처 문서를 참조합니다.

.. 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
 guaranteed to be supported.

 Up to four arguments may be passed in rbx, rcx, rdx, and rsi respectively.
 The hypercall number should be placed in rax and the return value will be
 placed in rax.  No other registers will be clobbered unless explicitly stated
 by the particular hypercall.

S390:
  R2-R7 are used for parameters 1-6. In addition, R1 is used for hypercall
  number. The return value is written to R2.

  S390 uses diagnose instruction as hypercall (0x500) along with hypercall
  number in R1.

  For further information on the S390 diagnose call as supported by KVM,
  refer to Documentation/virt/kvm/s390/s390-diag.rst.

PowerPC:
  It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers.
  Return value is placed in R3.

  KVM hypercalls uses 4 byte opcode, that are patched with 'hypercall-instructions'
  property inside the device tree's /hypervisor node.
  For more information refer to Documentation/virt/kvm/ppc-pv.rst

MIPS:
  KVM hypercalls use the HYPCALL instruction with code 0 and the hypercall
  number in $2 (v0). Up to four arguments may be placed in $4-$7 (a0-a3) and
  the return value is placed in $2 (v0).

KVM Hypercalls Documentation

하이퍼콜 문서 형식

각 하이퍼콜은 이름, 지원 아키텍처, deprecated·obsolete·active 상태, 목적의 네 항목으로 정의됩니다.

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

The template for each hypercall is:
1. Hypercall name.
2. Architecture(s)
3. Status (deprecated, obsolete, active)
4. Purpose

KVM_HC_VAPIC_POLL_IRQ

x86 active 하이퍼콜로 guest exit를 유발해 host가 재진입할 때 pending interrupt를 확인하게 합니다.

1. KVM_HC_VAPIC_POLL_IRQ
------------------------

:Architecture: x86
:Status: active
:Purpose: Trigger guest exit so that the host can check for pending
          interrupts on reentry.

KVM_HC_MMU_OP

x86의 deprecated 하이퍼콜로 PTE 쓰기, TLB flush, page table 해제 같은 MMU operation을 지원했습니다.

2. KVM_HC_MMU_OP
----------------

:Architecture: x86
:Status: deprecated.
:Purpose: Support MMU operations such as writing to PTE,
          flushing TLB, release PT.

KVM_HC_FEATURES

PowerPC guest에 사용 가능한 하이퍼콜을 노출합니다. x86은 CPUID를 사용하지만 PPC는 ePAPR device tree lookup 또는 이 KVM 전용 enumeration을 사용할 수 있습니다.

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.

KVM_HC_PPC_MAP_MAGIC_PAGE

PowerPC guest가 supervisor-visible register state 일부를 담은 shared magic page를 매핑해 memory load/store로 register에 접근하게 합니다.

4. KVM_HC_PPC_MAP_MAGIC_PAGE
----------------------------

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

KVM_HC_KICK_CPU

x86에서 HLT 상태로 잠든 vCPU를 깨웁니다. PV guest vCPU가 spinlock 같은 event를 기다리며 일정 시간 busy-wait한 뒤 HLT하면 hypervisor가 sleep시킬 수 있고, 다른 vCPU가 target APIC ID를 지정해 깨웁니다.

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
  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
  the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the
  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.

KVM_HC_CLOCK_PAIRING

host와 guest clock을 동기화합니다. `a0`은 host가 `struct kvm_clock_pairing`을 복사할 guest physical address, `a1`은 clock type이며 현재 `KVM_CLOCK_PAIRING_WALLCLOCK (0)`만 지원합니다.

guest는 반환 TSC로 같은 시점의 자체 CLOCK_REALTIME을 계산할 수 있습니다. host clocksource가 TSC가 아니거나 clock type이 다르면 `KVM_EOPNOTSUPP`입니다.

6. KVM_HC_CLOCK_PAIRING
-----------------------
:Architecture: x86
:Status: active
:Purpose: Hypercall used to synchronize host and guest clocks.

Usage:

a0: guest physical address where host copies
"struct kvm_clock_offset" structure.

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;
			__u64 tsc;
			__u32 flags;
			__u32 pad[9];
		};

       Where:
               * sec: seconds from clock_type clock.
               * nsec: nanoseconds from clock_type clock.
               * tsc: guest TSC value used to calculate sec/nsec pair
               * flags: flags, unused (0) at the moment.

The hypercall lets a guest compute a precise timestamp across
host and guest.  The guest can use the returned TSC value to
compute the CLOCK_REALTIME for its clock, at the same instant.

Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource,
or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK.

KVM_HC_SEND_IPI

x86 guest가 여러 vCPU에 multicast IPI를 보냅니다. 64-bit mode는 호출당 최대 128개 destination, 32-bit mode는 64개 vCPU를 표현하며 성공적으로 전달한 CPU 수를 반환합니다.

`a0` bit 0은 `a2` APIC ID, bit 1은 `a2+1`에 대응하며 이후도 같은 방식입니다.

7. KVM_HC_SEND_IPI
------------------

: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

The hypercall lets a guest send multicast IPIs, with at most 128
128 destinations per hypercall in 64-bit mode and 64 vCPUs per
hypercall in 32-bit mode.  The destinations are represented by a
bitmap contained in the first two arguments (a0 and a1). Bit 0 of
a0 corresponds to the APIC ID in the third argument (a2), bit 1
corresponds to the APIC ID a2+1, and so on.

Returns the number of CPUs to which the IPIs were delivered successfully.

KVM_HC_SCHED_YIELD

x86에서 IPI target vCPU가 preempt된 경우 현재 vCPU가 양보합니다. `a0`은 destination APIC ID이며 call-function IPI-many를 보낼 때 target 중 하나가 preempt되었다면 yield하는 용도로 사용합니다.

8. KVM_HC_SCHED_YIELD
---------------------

: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
	        any of the IPI target vCPUs was preempted.

KVM_HC_MAP_GPA_RANGE

x86 guest가 지정 속성으로 연속 GPA range를 매핑하도록 KVM에 요청합니다. `a0`은 시작 guest physical address, `a1`은 연속 4KB page 수, `a2`는 속성입니다.

이 하이퍼콜은 `KVM_CAP_EXIT_HYPERCALL`로 userspace에서 구현합니다. userspace는 guest CPUID에 `KVM_FEATURE_HC_MAP_GPA_RANGE`를 알리기 전에 capability를 켜야 합니다. guest가 `KVM_FEATURE_MIGRATION_CONTROL`도 지원하면 `MSR_KVM_MIGRATION_CONTROL` write를 처리할 MSR filter도 구성해야 합니다.

9. KVM_HC_MAP_GPA_RANGE
-------------------------
:Architecture: x86
:Status: active
:Purpose: Request KVM to map a GPA range with the specified attributes.

a0: the guest physical address of the start page
a1: the number of (4kb) pages (must be contiguous in GPA space)
a2: attributes

    Where 'attributes' :
        * bits  3:0 - preferred page size encoding 0 = 4kb, 1 = 2mb, 2 = 1gb, etc...
        * bit     4 - plaintext = 0, encrypted = 1
        * bits 63:5 - reserved (must be zero)

**Implementation note**: this hypercall is implemented in userspace via
the KVM_CAP_EXIT_HYPERCALL capability. Userspace must enable that capability
before advertising KVM_FEATURE_HC_MAP_GPA_RANGE in the guest CPUID.  In
addition, if the guest supports KVM_FEATURE_MIGRATION_CONTROL, userspace
must also set up an MSR filter to process writes to MSR_KVM_MIGRATION_CONTROL.