Nested KVM on POWER

POWER nested KVM

이 문서는 POWER에서 guest operating system이 hypervisor 역할을 하며 nested guest를 실행하는 KVM API를 설명합니다.

L0·L1·L2 모델

Hypervisor가 필요한 hypercall을 구현했다면 guest OS가 다시 hypervisor가 되어 nested guest를 실행할 수 있습니다.

기존 v1 API

Linux/KVM은 2018년부터 L0와 L1 양쪽의 nesting을 지원합니다. L0 framework와 hcall stub은 다음 commit에서 추가되었습니다.

commit 8e3f5fc1045dc49fd175b978c5457f5f51e7a2ce
Author: Paul Mackerras <[email protected]>
Date:   Mon Oct 8 16:31:03 2018 +1100
KVM: PPC: Book3S HV: Framework and hcall stubs for nested virtualization

L1의 nested guest entry code는 다음 commit에서 추가되었습니다.

commit 360cae313702cdd0b90f82c261a8302fecef030a
Author: Paul Mackerras <[email protected]>
Date:   Mon Oct 8 16:31:04 2018 +1100
KVM: PPC: Book3S HV: Nested guest entry via hypercall

v1 API의 중심은 `h_enter_nested()`입니다. L1은 전체 L2 vCPU state를 넘겨 실행을 요청하고, L0는 exit condition까지 L2를 실행한 뒤 전체 state를 L1에 돌려줍니다.

L0는 L1→L2 entry와 L2→L1 exit의 짧은 구간 외에는 L2 vCPU state를 유지하지 않습니다. 영구적으로 유지하는 유일한 state는 L1이 `h_set_partition_table()`로 등록한 partition table이며 shadow page table 같은 나머지는 cache입니다.

L1은 L2나 vCPU를 미리 등록하지 않고도 `h_enter_nested()`를 호출할 수 있습니다. 이 호출이 L2와 vCPU 생성을 암묵적으로 수행합니다. 문서에서는 이를 v1 API라고 부릅니다.

새 PAPR v2 API와 lifecycle

v2 API는 L2와 vCPU 생성을 명시적으로 바꿉니다. `h_enter_nested()` 대신 `H_GUEST_VCPU_RUN()`을 사용하며, 먼저 `H_GUEST_CREATE()`와 `H_GUEST_CREATE_VCPU()`를 호출해야 합니다.

vCPU state는 `H_GUEST_GET_STATE()`와 `H_GUEST_SET_STATE()` 계열 hcall로 주고받습니다.

• L1과 L0가 `H_GUEST_GET_CAPABILITIES()` 및 `H_GUEST_SET_CAPABILITIES()`로 capability를 협상합니다. 보통 L1 boot 때 수행합니다.
• L1이 `H_GUEST_CREATE()`로 L2 생성을 요청하고 token을 받습니다.
• L1이 `H_GUEST_CREATE_VCPU()`로 L2 vCPU를 만듭니다.
• `H_GUEST_GET_STATE()`와 `H_GUEST_SET_STATE()`로 vCPU state를 교환합니다.
• `H_GUEST_VCPU_RUN()` 또는 문서 signature의 `H_GUEST_RUN_VCPU()`로 vCPU를 실행합니다.
• 마지막에 `H_GUEST_DELETE()`로 L2와 모든 vCPU를 삭제합니다.

HCALL 설명의 범위

이 설명은 API 전체 구조를 이해하기 위한 것이며 L0 또는 L1 구현에 필요한 모든 세부 사항을 제공하지는 않습니다. 최신 PAPR specification을 함께 참조해야 합니다.

아래 HCALL은 모두 L1이 L0에 호출합니다.

`H_GUEST_GET_CAPABILITIES()`

L0 nested hypervisor가 L2로 지원하는 CPU version(예: POWER9, POWER10)을 포함한 capability를 조회합니다. `flags`는 reserved이고 R3에 return code, R4에 capability bitmap 1이 반환됩니다.

H_GUEST_GET_CAPABILITIES(uint64 flags)

Parameters:
  Input:
    flags: Reserved
  Output:
    R3: Return code
    R4: Hypervisor Supported Capabilities bitmap 1

`H_GUEST_SET_CAPABILITIES()`

L1이 자신이 사용할 capability를 L0에 알립니다. 일반적으로 GET 결과 중 subset을 SET하여 양쪽이 합의한 capability 집합을 정합니다.

H_GUEST_SET_CAPABILITIES(uint64 flags,
                         uint64 capabilitiesBitmap1)
Parameters:
  Input:
    flags: Reserved
    capabilitiesBitmap1: Only capabilities advertised through
                         H_GUEST_GET_CAPABILITIES
  Output:
    R3: Return code
    R4: If R3 = H_P2: The number of invalid bitmaps
    R5: If R3 = H_P2: The index of first invalid bitmap

광고되지 않은 bitmap을 넘겨 `H_P2`가 반환되면 R4는 invalid bitmap 수, R5는 첫 invalid bitmap index입니다.

`H_GUEST_CREATE()`

L2를 만들고 이후 HCALL에서 식별할 unique ID를 반환합니다. 이 ID는 LPID와 비슷한 역할을 합니다.

H_GUEST_CREATE(uint64 flags,
               uint64 continueToken);
Parameters:
  Input:
    flags: Reserved
    continueToken: Initial call set to -1. Subsequent calls,
                   after H_Busy or H_LongBusyOrder has been
                   returned, value that was returned in R4.
  Output:
    R3: Return code. Notable:
      H_Not_Enough_Resources: Unable to create Guest VCPU due to not
      enough Hypervisor memory. See H_GUEST_CREATE_GET_STATE(flags =
      takeOwnershipOfVcpuState)
    R4: If R3 = H_Busy or_H_LongBusyOrder -> continueToken

첫 호출의 `continueToken`은 `-1`입니다. `H_Busy` 또는 `H_LongBusyOrder` 뒤에는 R4에서 받은 token으로 이어서 호출합니다. Hypervisor memory가 부족하면 `H_Not_Enough_Resources`가 반환될 수 있습니다.

`H_GUEST_CREATE_VCPU()`

지정한 L2에 vCPU를 만듭니다. `guestId`는 `H_GUEST_CREATE()` 결과이고 L1이 배정하는 `vcpuId`는 해당 L2 안에서 고유해야 하며 `0..2047` 범위입니다.

H_GUEST_CREATE_VCPU(uint64 flags,
                    uint64 guestId,
                    uint64 vcpuId);
Parameters:
  Input:
    flags: Reserved
    guestId: ID obtained from H_GUEST_CREATE
    vcpuId: ID of the vCPU to be created. This must be within the
            range of 0 to 2047
  Output:
    R3: Return code. Notable:
      H_Not_Enough_Resources: Unable to create Guest VCPU due to not
      enough Hypervisor memory. See H_GUEST_CREATE_GET_STATE(flags =
      takeOwnershipOfVcpuState)

vCPU state를 위한 hypervisor memory가 부족하면 `H_Not_Enough_Resources`가 반환될 수 있습니다.

`H_GUEST_GET_STATE()`

L2 전체 또는 특정 vCPU에 연관된 state를 Guest State Buffer(GSB)로 읽습니다. Guest-wide 예시는 timebase offset과 process-scoped page table이고 vCPU-specific 예시는 GPR과 VSR입니다.

Flag bit가 guest-wide, host-wide 또는 vCPU-specific 요청을 구분하며 GSB 안의 ID도 scope와 일치해야 합니다. Host-wide 요청에서는 `guestId`와 `vcpuId`를 무시하고 guest/vCPU state element를 요청하면 오류입니다.

L1은 GSB의 element ID와 size만 채우고, L0가 각 ID의 value를 씁니다. `dataBuffer`는 L1 real address입니다.

H_GUEST_GET_STATE(uint64 flags,
                         uint64 guestId,
                         uint64 vcpuId,
                         uint64 dataBuffer,
                         uint64 dataBufferSizeInBytes);
Parameters:
  Input:
    flags:
       Bit 0: getGuestWideState: Request state of the Guest instead
         of an individual VCPU.
       Bit 1: getHostWideState: Request stats of the Host. This causes
         the guestId and vcpuId parameters to be ignored and attempting
         to get the VCPU/Guest state will cause an error.
       Bits 2-63: Reserved
    guestId: ID obtained from H_GUEST_CREATE
    vcpuId: ID of the vCPU pass to H_GUEST_CREATE_VCPU
    dataBuffer: A L1 real address of the GSB.
      If takeOwnershipOfVcpuState, size must be at least the size
      returned by ID=0x0001
    dataBufferSizeInBytes: Size of dataBuffer
  Output:
    R3: Return code
    R4: If R3 = H_Invalid_Element_Id: The array index of the bad
          element ID.
        If R3 = H_Invalid_Element_Size: The array index of the bad
           element size.
        If R3 = H_Invalid_Element_Value: The array index of the bad
           element value.

Invalid element ID, size 또는 value가 있으면 R4에 문제가 있는 array index가 반환됩니다.

`H_GUEST_SET_STATE()`

L2-wide 또는 vCPU-specific state를 GSB로 설정합니다. Scope 예시와 ID 일치 규칙은 GET과 같습니다.

SET에서는 L1이 GSB의 모든 value를 쓰고 L0는 이를 읽기만 합니다. `returnOwnershipOfVcpuState` flag는 GET의 `takeOwnershipOfVcpuState`와 짝을 이룹니다.

H_GUEST_SET_STATE(uint64 flags,
                  uint64 guestId,
                  uint64 vcpuId,
                  uint64 dataBuffer,
                  uint64 dataBufferSizeInBytes);
Parameters:
  Input:
    flags:
       Bit 0: getGuestWideState: Request state of the Guest instead
         of an individual VCPU.
       Bit 1: returnOwnershipOfVcpuState Return Guest VCPU state. See
         GET_STATE takeOwnershipOfVcpuState
       Bits 2-63: Reserved
    guestId: ID obtained from H_GUEST_CREATE
    vcpuId: ID of the vCPU pass to H_GUEST_CREATE_VCPU
    dataBuffer: A L1 real address of the GSB.
      If takeOwnershipOfVcpuState, size must be at least the size
      returned by ID=0x0001
    dataBufferSizeInBytes: Size of dataBuffer
  Output:
    R3: Return code
    R4: If R3 = H_Invalid_Element_Id: The array index of the bad
          element ID.
        If R3 = H_Invalid_Element_Size: The array index of the bad
           element size.
        If R3 = H_Invalid_Element_Value: The array index of the bad
           element value.

Invalid element ID, size 또는 value에 대해서는 GET과 마찬가지로 R4가 문제가 있는 element index를 반환합니다.

`H_GUEST_RUN_VCPU()`

미리 `H_GUEST_SET_STATE()`로 설정한 state를 사용해 L2 vCPU를 실행합니다. L2가 exit하면 L1은 이 hcall 다음 위치에서 다시 실행됩니다.

성능을 위해 input/output GSB pointer는 hcall parameter로 매번 전달하지 않습니다. ID `0x0C00`과 `0x0C01`을 사용한 `H_GUEST_SET_STATE()`로 먼저 등록합니다.

Input GSB는 vCPU-specific element만 포함하며 설정할 것이 없으면 첫 4 byte의 element count를 0으로 둘 수 있습니다. Output GSB의 element는 L0가 exit type에 따라 채웁니다.

Exit reason은 GPR4에 들어갑니다. 예를 들어 L2 hcall exit `0xC00`에서는 service에 필요한 GPR3-12가 output GSB에 제공되며 추가 state는 `H_GUEST_GET_STATE()`로 읽습니다.

L1은 run flag로 external interrupt, privileged doorbell 또는 system reset interrupt를 L0가 합성하도록 요청할 수 있습니다. 또는 SET_STATE나 input GSB로 직접 적절한 state를 만들 수 있습니다.

H_GUEST_RUN_VCPU(uint64 flags,
                 uint64 guestId,
                 uint64 vcpuId,
                 uint64 dataBuffer,
                 uint64 dataBufferSizeInBytes);
Parameters:
  Input:
    flags:
       Bit 0: generateExternalInterrupt: Generate an external interrupt
       Bit 1: generatePrivilegedDoorbell: Generate a Privileged Doorbell
       Bit 2: sendToSystemReset”: Generate a System Reset Interrupt
       Bits 3-63: Reserved
    guestId: ID obtained from H_GUEST_CREATE
    vcpuId: ID of the vCPU pass to H_GUEST_CREATE_VCPU
  Output:
    R3: Return code
    R4: If R3 = H_Success: The reason L1 VCPU exited (ie. NIA)
          0x000: The VCPU stopped running for an unspecified reason. An
            example of this is the Hypervisor stopping a VCPU running
            due to an outstanding interrupt for the Host Partition.
          0x980: HDEC
          0xC00: HCALL
          0xE00: HDSI
          0xE20: HISI
          0xE40: HEA
          0xF80: HV Fac Unavail
        If R3 = H_Invalid_Element_Id, H_Invalid_Element_Size, or
          H_Invalid_Element_Value: R4 is offset of the invalid element
          in the input buffer.

`H_GUEST_DELETE()`

L2를 삭제하면 연결된 모든 vCPU도 함께 삭제됩니다. 별도의 vCPU delete HCALL은 없습니다.

`kdump` 또는 `kexec`에서 L0를 reset할 때는 `deleteAllGuests` flag로 모든 guest를 삭제할 수 있습니다.

H_GUEST_DELETE(uint64 flags,
               uint64 guestId)
Parameters:
  Input:
    flags:
       Bit 0: deleteAllGuests: deletes all guests
       Bits 1-63: Reserved
    guestId: ID obtained from H_GUEST_CREATE
  Output:
    R3: Return code

Guest State Buffer 개요

GSB는 `H_GUEST_GET_STATE()`, `H_GUEST_SET_STATE()`와 `H_GUEST_VCPU_RUN()` 사이에서 L1과 L0가 L2 state를 교환하는 주된 형식입니다.

State는 L2 전체(timebase offset 등) 또는 특정 vCPU(GPR 등)에 속할 수 있습니다. RUN call에서는 L2 vCPU state만 설정할 수 있습니다.

PAPR 관례에 따라 GSB의 모든 data는 big-endian입니다.

GSB header와 element 형식

GSB state ID 전체 표

Element ID는 architecture state(GPR, VSR, SPR)와 timebase offset, partition/process-scoped page table 같은 metadata를 지정합니다. Scope는 H(host), G(guest-wide), T(thread/vCPU)입니다.

ptregs/hvregs 밖의 state

v1 API에서는 vector register와 일부 SPR처럼 `ptregs`/`hvstate`에 없는 state가 있습니다. L1이 `h_enter_nested()` 전에 실제 hardware register에 값을 올리고 L0가 건드리지 않아 L2 state로 이어지게 합니다.

v2 API는 이 암묵적 전달을 제거하고 모든 해당 state를 GSB로 명시적으로 설정합니다.

L1 state cache와 lazy update

v1은 `h_enter_nested()`마다 모든 state를 양방향 전송하고, L2가 실행 중이 아니면 L0가 partition table 위치 외의 state를 유지하지 않습니다.

v2에서는 vCPU가 멈춘 뒤에도 L0가 L2 state를 유지합니다. 따라서 L1은 state를 변경하거나 cache가 낡았을 때만 L0와 통신하면 됩니다.

`H_GUEST_RUN_VCPU()` exit 뒤 L1은 내부 L2 state를 invalid로 표시합니다. 이후 `kvm_get_one_reg()` 같은 조회가 오면 `H_GUEST_GET_STATE()`로 읽고 다음 run까지 valid로 둡니다.

L1이 `kvm_set_one_reg()`로 state를 바꿀 때도 즉시 L0에 쓰지 않고 내부 copy를 갱신합니다. 다음 run 때 `H_GUEST_VCPU_RUN()` input buffer로 flush합니다.

이 lazy update는 불필요한 `H_GUEST_GET_STATE()`와 `H_GUEST_SET_STATE()` 호출을 줄입니다.