요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
=======================================
4
Internal ABI between the kernel and HYP
5
=======================================
7
This file documents the interaction between the Linux kernel and the
8
hypervisor layer when running Linux as a hypervisor (for example
9
KVM). It doesn't cover the interaction of the kernel with the
10
hypervisor when running as a guest (under Xen, KVM or any other
11
hypervisor), or any hypervisor-specific interaction when the kernel is
12
used as a host.
14
Note: KVM/arm has been removed from the kernel. The API described
15
here is still valid though, as it allows the kernel to kexec when
16
booted at HYP. It can also be used by a hypervisor other than KVM
17
if necessary.
19
On arm and arm64 (without VHE), the kernel doesn't run in hypervisor
20
mode, but still needs to interact with it, allowing a built-in
21
hypervisor to be either installed or torn down.
23
In order to achieve this, the kernel must be booted at HYP (arm) or
24
EL2 (arm64), allowing it to install a set of stubs before dropping to
25
SVC/EL1. These stubs are accessible by using a 'hvc #0' instruction,
26
and only act on individual CPUs.
28
Unless specified otherwise, any built-in hypervisor must implement
29
these functions (see arch/arm{,64}/include/asm/virt.h):
31
* ::
33
r0/x0 = HVC_SET_VECTORS
34
r1/x1 = vectors
36
Set HVBAR/VBAR_EL2 to 'vectors' to enable a hypervisor. 'vectors'
37
must be a physical address, and respect the alignment requirements
38
of the architecture. Only implemented by the initial stubs, not by
39
Linux hypervisors.
41
* ::
43
r0/x0 = HVC_RESET_VECTORS
45
Turn HYP/EL2 MMU off, and reset HVBAR/VBAR_EL2 to the initials
46
stubs' exception vector value. This effectively disables an existing
47
hypervisor.
49
* ::
51
r0/x0 = HVC_SOFT_RESTART
52
r1/x1 = restart address
53
x2 = x0's value when entering the next payload (arm64)
54
x3 = x1's value when entering the next payload (arm64)
55
x4 = x2's value when entering the next payload (arm64)
57
Mask all exceptions, disable the MMU, clear I+D bits, move the arguments
58
into place (arm64 only), and jump to the restart address while at HYP/EL2.
59
This hypercall is not expected to return to its caller.
61
* ::
63
x0 = HVC_FINALISE_EL2 (arm64 only)
65
Finish configuring EL2 depending on the command-line options,
66
including an attempt to upgrade the kernel's exception level from
67
EL1 to EL2 by enabling the VHE mode. This is conditioned by the CPU
68
supporting VHE, the EL2 MMU being off, and VHE not being disabled by
69
any other means (command line option, for example).
71
Any other value of r0/x0 triggers a hypervisor-specific handling,
72
which is not documented here.
74
The return value of a stub hypercall is held by r0/x0, and is 0 on
75
success, and HVC_STUB_ERR on error. A stub hypercall is allowed to
76
clobber any of the caller-saved registers (x0-x18 on arm64, r0-r3 and
77
ip on arm). It is thus recommended to use a function call to perform
78
the hypercall.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
HYP·EL2 stub hypercall ABI
1-78이 ABI는 Linux가 KVM 같은 hypervisor로 동작할 때 kernel과 hypervisor layer가 상호작용하는 방법을 설명합니다. Xen·KVM guest로 실행할 때 host hypervisor와 통신하는 ABI나 host kernel의 hypervisor-specific interface는 범위 밖입니다.
KVM/arm은 kernel에서 제거됐지만 이 API는 HYP에서 부팅한 kernel이 `kexec`할 수 있게 하므로 여전히 유효합니다. 필요하면 KVM이 아닌 built-in hypervisor도 사용할 수 있습니다.
VHE가 없는 arm과 arm64에서 kernel은 hypervisor mode에 머물지 않지만 built-in hypervisor를 설치하거나 제거해야 합니다. Kernel은 arm의 HYP 또는 arm64의 EL2에서 부팅되어 stub을 설치한 뒤 SVC/EL1으로 내려가며 CPU별 stub은 `hvc #0`으로 호출합니다.
FunctionRegister와 동작
`HVC_SET_VECTORS``r0/x0` command, `r1/x1` physical vector address. Architecture alignment를 지켜 `HVBAR/VBAR_EL2` 설정; initial stub만 구현
`HVC_RESET_VECTORS`HYP/EL2 MMU를 끄고 `HVBAR/VBAR_EL2`를 initial-stub exception vector로 reset해 기존 hypervisor 비활성화
`HVC_SOFT_RESTART`Exception mask, MMU disable, I+D bit clear 후 restart address로 HYP/EL2 jump. arm64의 `x2-x4`는 다음 payload의 `x0-x2` 값이며 return하지 않음
`HVC_FINALISE_EL2`arm64 전용. Command line과 CPU 조건에 따라 EL2 구성을 마치고 VHE를 enable해 EL1에서 EL2로 kernel exception level upgrade 시도
별도 언급이 없으면 built-in hypervisor가 구현해야 하는 CPU-local function입니다.
`HVC_FINALISE_EL2`의 VHE 전환은 CPU가 VHE를 지원하고 EL2 MMU가 꺼져 있으며 command line 등 다른 수단으로 VHE가 disable되지 않은 경우에만 가능합니다.
`r0/x0`의 다른 값은 이 문서가 정의하지 않는 hypervisor-specific 처리로 넘어갑니다. Stub hypercall 반환값은 `r0/x0`에 있으며 성공은 0, 오류는 `HVC_STUB_ERR`입니다.
Stub은 caller-saved register를 덮어쓸 수 있습니다. 범위는 arm64의 `x0-x18`, arm의 `r0-r3`와 `ip`이므로 inline sequence보다 정상 function call로 hypercall을 수행하는 것이 권장됩니다.
.. SPDX-License-Identifier: GPL-2.0
=======================================
Internal ABI between the kernel and HYP
=======================================
This file documents the interaction between the Linux kernel and the
hypervisor layer when running Linux as a hypervisor (for example
KVM). It doesn't cover the interaction of the kernel with the
hypervisor when running as a guest (under Xen, KVM or any other
hypervisor), or any hypervisor-specific interaction when the kernel is
used as a host.
Note: KVM/arm has been removed from the kernel. The API described
here is still valid though, as it allows the kernel to kexec when
booted at HYP. It can also be used by a hypervisor other than KVM
if necessary.
On arm and arm64 (without VHE), the kernel doesn't run in hypervisor
mode, but still needs to interact with it, allowing a built-in
hypervisor to be either installed or torn down.
In order to achieve this, the kernel must be booted at HYP (arm) or
EL2 (arm64), allowing it to install a set of stubs before dropping to
SVC/EL1. These stubs are accessible by using a 'hvc #0' instruction,
and only act on individual CPUs.
Unless specified otherwise, any built-in hypervisor must implement
these functions (see arch/arm{,64}/include/asm/virt.h):
* ::
r0/x0 = HVC_SET_VECTORS
r1/x1 = vectors
Set HVBAR/VBAR_EL2 to 'vectors' to enable a hypervisor. 'vectors'
must be a physical address, and respect the alignment requirements
of the architecture. Only implemented by the initial stubs, not by
Linux hypervisors.
* ::
r0/x0 = HVC_RESET_VECTORS
Turn HYP/EL2 MMU off, and reset HVBAR/VBAR_EL2 to the initials
stubs' exception vector value. This effectively disables an existing
hypervisor.
* ::
r0/x0 = HVC_SOFT_RESTART
r1/x1 = restart address
x2 = x0's value when entering the next payload (arm64)
x3 = x1's value when entering the next payload (arm64)
x4 = x2's value when entering the next payload (arm64)
Mask all exceptions, disable the MMU, clear I+D bits, move the arguments
into place (arm64 only), and jump to the restart address while at HYP/EL2.
This hypercall is not expected to return to its caller.
* ::
x0 = HVC_FINALISE_EL2 (arm64 only)
Finish configuring EL2 depending on the command-line options,
including an attempt to upgrade the kernel's exception level from
EL1 to EL2 by enabling the VHE mode. This is conditioned by the CPU
supporting VHE, the EL2 MMU being off, and VHE not being disabled by
any other means (command line option, for example).
Any other value of r0/x0 triggers a hypervisor-specific handling,
which is not documented here.
The return value of a stub hypercall is held by r0/x0, and is 0 on
success, and HVC_STUB_ERR on error. A stub hypercall is allowed to
clobber any of the caller-saved registers (x0-x18 on arm64, r0-r3 and
ip on arm). It is thus recommended to use a function call to perform
the hypercall.
요약·해설
hyp-abi.rst:1-78HYP·EL2에서 부팅한 Linux가 hypervisor vector를 설치·reset하고 soft restart·VHE finalization을 수행하는 stub ABI입니다.
API 이름, register, function ID, source path와 error code는 원문 표기를 유지했습니다.