요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
===============================================
4
KVM/arm64-specific hypercalls exposed to guests
5
===============================================
7
This file documents the KVM/arm64-specific hypercalls which may be
8
exposed by KVM/arm64 to guest operating systems. These hypercalls are
9
issued using the HVC instruction according to version 1.1 of the Arm SMC
10
Calling Convention (DEN0028/C):
12
https://developer.arm.com/docs/den0028/c
14
All KVM/arm64-specific hypercalls are allocated within the "Vendor
15
Specific Hypervisor Service Call" range with a UID of
16
``28b46fb6-2ec5-11e9-a9ca-4b564d003a74``. This UID should be queried by the
17
guest using the standard "Call UID" function for the service range in
18
order to determine that the KVM/arm64-specific hypercalls are available.
20
``ARM_SMCCC_VENDOR_HYP_KVM_FEATURES_FUNC_ID``
21
---------------------------------------------
23
Provides a discovery mechanism for other KVM/arm64 hypercalls.
25
+---------------------+-------------------------------------------------------------+
26
| Presence: | Mandatory for the KVM/arm64 UID |
27
+---------------------+-------------------------------------------------------------+
28
| Calling convention: | HVC32 |
29
+---------------------+----------+--------------------------------------------------+
30
| Function ID: | (uint32) | 0x86000000 |
31
+---------------------+----------+--------------------------------------------------+
32
| Arguments: | None |
33
+---------------------+----------+----+---------------------------------------------+
34
| Return Values: | (uint32) | R0 | Bitmap of available function numbers 0-31 |
35
| +----------+----+---------------------------------------------+
36
| | (uint32) | R1 | Bitmap of available function numbers 32-63 |
37
| +----------+----+---------------------------------------------+
38
| | (uint32) | R2 | Bitmap of available function numbers 64-95 |
39
| +----------+----+---------------------------------------------+
40
| | (uint32) | R3 | Bitmap of available function numbers 96-127 |
41
+---------------------+----------+----+---------------------------------------------+
43
``ARM_SMCCC_VENDOR_HYP_KVM_PTP_FUNC_ID``
44
----------------------------------------
46
See ptp_kvm.rst
48
``ARM_SMCCC_KVM_FUNC_HYP_MEMINFO``
49
----------------------------------
51
Query the memory protection parameters for a pKVM protected virtual machine.
53
+---------------------+-------------------------------------------------------------+
54
| Presence: | Optional; pKVM protected guests only. |
55
+---------------------+-------------------------------------------------------------+
56
| Calling convention: | HVC64 |
57
+---------------------+----------+--------------------------------------------------+
58
| Function ID: | (uint32) | 0xC6000002 |
59
+---------------------+----------+----+---------------------------------------------+
60
| Arguments: | (uint64) | R1 | Reserved / Must be zero |
61
| +----------+----+---------------------------------------------+
62
| | (uint64) | R2 | Reserved / Must be zero |
63
| +----------+----+---------------------------------------------+
64
| | (uint64) | R3 | Reserved / Must be zero |
65
+---------------------+----------+----+---------------------------------------------+
66
| Return Values: | (int64) | R0 | ``INVALID_PARAMETER (-3)`` on error, else |
67
| | | | memory protection granule in bytes |
68
+---------------------+----------+----+---------------------------------------------+
70
``ARM_SMCCC_KVM_FUNC_MEM_SHARE``
71
--------------------------------
73
Share a region of memory with the KVM host, granting it read, write and execute
74
permissions. The size of the region is equal to the memory protection granule
75
advertised by ``ARM_SMCCC_KVM_FUNC_HYP_MEMINFO``.
77
+---------------------+-------------------------------------------------------------+
78
| Presence: | Optional; pKVM protected guests only. |
79
+---------------------+-------------------------------------------------------------+
80
| Calling convention: | HVC64 |
81
+---------------------+----------+--------------------------------------------------+
82
| Function ID: | (uint32) | 0xC6000003 |
83
+---------------------+----------+----+---------------------------------------------+
84
| Arguments: | (uint64) | R1 | Base IPA of memory region to share |
85
| +----------+----+---------------------------------------------+
86
| | (uint64) | R2 | Reserved / Must be zero |
87
| +----------+----+---------------------------------------------+
88
| | (uint64) | R3 | Reserved / Must be zero |
89
+---------------------+----------+----+---------------------------------------------+
90
| Return Values: | (int64) | R0 | ``SUCCESS (0)`` |
91
| | | +---------------------------------------------+
92
| | | | ``INVALID_PARAMETER (-3)`` |
93
+---------------------+----------+----+---------------------------------------------+
95
``ARM_SMCCC_KVM_FUNC_MEM_UNSHARE``
96
----------------------------------
98
Revoke access permission from the KVM host to a memory region previously shared
99
with ``ARM_SMCCC_KVM_FUNC_MEM_SHARE``. The size of the region is equal to the
100
memory protection granule advertised by ``ARM_SMCCC_KVM_FUNC_HYP_MEMINFO``.
102
+---------------------+-------------------------------------------------------------+
103
| Presence: | Optional; pKVM protected guests only. |
104
+---------------------+-------------------------------------------------------------+
105
| Calling convention: | HVC64 |
106
+---------------------+----------+--------------------------------------------------+
107
| Function ID: | (uint32) | 0xC6000004 |
108
+---------------------+----------+----+---------------------------------------------+
109
| Arguments: | (uint64) | R1 | Base IPA of memory region to unshare |
110
| +----------+----+---------------------------------------------+
111
| | (uint64) | R2 | Reserved / Must be zero |
112
| +----------+----+---------------------------------------------+
113
| | (uint64) | R3 | Reserved / Must be zero |
114
+---------------------+----------+----+---------------------------------------------+
115
| Return Values: | (int64) | R0 | ``SUCCESS (0)`` |
116
| | | +---------------------------------------------+
117
| | | | ``INVALID_PARAMETER (-3)`` |
118
+---------------------+----------+----+---------------------------------------------+
120
``ARM_SMCCC_KVM_FUNC_MMIO_GUARD``
121
----------------------------------
123
Request that a given memory region is handled as MMIO by the hypervisor,
124
allowing accesses to this region to be emulated by the KVM host. The size of the
125
region is equal to the memory protection granule advertised by
126
``ARM_SMCCC_KVM_FUNC_HYP_MEMINFO``.
128
+---------------------+-------------------------------------------------------------+
129
| Presence: | Optional; pKVM protected guests only. |
130
+---------------------+-------------------------------------------------------------+
131
| Calling convention: | HVC64 |
132
+---------------------+----------+--------------------------------------------------+
133
| Function ID: | (uint32) | 0xC6000007 |
134
+---------------------+----------+----+---------------------------------------------+
135
| Arguments: | (uint64) | R1 | Base IPA of MMIO memory region |
136
| +----------+----+---------------------------------------------+
137
| | (uint64) | R2 | Reserved / Must be zero |
138
| +----------+----+---------------------------------------------+
139
| | (uint64) | R3 | Reserved / Must be zero |
140
+---------------------+----------+----+---------------------------------------------+
141
| Return Values: | (int64) | R0 | ``SUCCESS (0)`` |
142
| | | +---------------------------------------------+
143
| | | | ``INVALID_PARAMETER (-3)`` |
144
+---------------------+----------+----+---------------------------------------------+
146
``ARM_SMCCC_VENDOR_HYP_KVM_DISCOVER_IMPL_VER_FUNC_ID``
147
-------------------------------------------------------
148
Request the target CPU implementation version information and the number of target
149
implementations for the Guest VM.
151
+---------------------+-------------------------------------------------------------+
152
| Presence: | Optional; KVM/ARM64 Guests only |
153
+---------------------+-------------------------------------------------------------+
154
| Calling convention: | HVC64 |
155
+---------------------+----------+--------------------------------------------------+
156
| Function ID: | (uint32) | 0xC6000040 |
157
+---------------------+----------+--------------------------------------------------+
158
| Arguments: | None |
159
+---------------------+----------+----+---------------------------------------------+
160
| Return Values: | (int64) | R0 | ``SUCCESS (0)`` |
161
| | | +---------------------------------------------+
162
| | | | ``NOT_SUPPORTED (-1)`` |
163
| +----------+----+---------------------------------------------+
164
| | (uint64) | R1 | Bits [63:32] Reserved/Must be zero |
165
| | | +---------------------------------------------+
166
| | | | Bits [31:16] Major version |
167
| | | +---------------------------------------------+
168
| | | | Bits [15:0] Minor version |
169
| +----------+----+---------------------------------------------+
170
| | (uint64) | R2 | Number of target implementations |
171
| +----------+----+---------------------------------------------+
172
| | (uint64) | R3 | Reserved / Must be zero |
173
+---------------------+----------+----+---------------------------------------------+
175
``ARM_SMCCC_VENDOR_HYP_KVM_DISCOVER_IMPL_CPUS_FUNC_ID``
176
-------------------------------------------------------
178
Request the target CPU implementation information for the Guest VM. The Guest kernel
179
will use this information to enable the associated errata.
181
+---------------------+-------------------------------------------------------------+
182
| Presence: | Optional; KVM/ARM64 Guests only |
183
+---------------------+-------------------------------------------------------------+
184
| Calling convention: | HVC64 |
185
+---------------------+----------+--------------------------------------------------+
186
| Function ID: | (uint32) | 0xC6000041 |
187
+---------------------+----------+----+---------------------------------------------+
188
| Arguments: | (uint64) | R1 | selected implementation index |
189
| +----------+----+---------------------------------------------+
190
| | (uint64) | R2 | Reserved / Must be zero |
191
| +----------+----+---------------------------------------------+
192
| | (uint64) | R3 | Reserved / Must be zero |
193
+---------------------+----------+----+---------------------------------------------+
194
| Return Values: | (int64) | R0 | ``SUCCESS (0)`` |
195
| | | +---------------------------------------------+
196
| | | | ``INVALID_PARAMETER (-3)`` |
197
| +----------+----+---------------------------------------------+
198
| | (uint64) | R1 | MIDR_EL1 of the selected implementation |
199
| +----------+----+---------------------------------------------+
200
| | (uint64) | R2 | REVIDR_EL1 of the selected implementation |
201
| +----------+----+---------------------------------------------+
202
| | (uint64) | R3 | AIDR_EL1 of the selected implementation |
203
+---------------------+----------+----+---------------------------------------------+
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Vendor hypercall UID와 feature discovery
1-47KVM/arm64-specific hypercall은 Arm SMC Calling Convention v1.1(DEN0028/C)에 따라 guest가 HVC instruction으로 발행합니다. 모든 call은 Vendor Specific Hypervisor Service Call 범위에 할당됩니다.
Service UID는 `28b46fb6-2ec5-11e9-a9ca-4b564d003a74`입니다. Guest는 해당 service range의 표준 Call UID function으로 이 값을 조회해 KVM/arm64 hypercall 존재 여부를 먼저 확인해야 합니다.
항목값
Function ID`0x86000000`
Arguments없음
R0사용 가능한 function number 0-31 bitmap
R1Function number 32-63 bitmap
R2Function number 64-95 bitmap
R3Function number 96-127 bitmap
다른 KVM/arm64 function number를 발견하는 필수 HVC32 call입니다.
`ARM_SMCCC_VENDOR_HYP_KVM_PTP_FUNC_ID`의 상세 ABI는 `ptp_kvm.rst`에서 정의합니다.
.. SPDX-License-Identifier: GPL-2.0
===============================================
KVM/arm64-specific hypercalls exposed to guests
===============================================
This file documents the KVM/arm64-specific hypercalls which may be
exposed by KVM/arm64 to guest operating systems. These hypercalls are
issued using the HVC instruction according to version 1.1 of the Arm SMC
Calling Convention (DEN0028/C):
https://developer.arm.com/docs/den0028/c
All KVM/arm64-specific hypercalls are allocated within the "Vendor
Specific Hypervisor Service Call" range with a UID of
``28b46fb6-2ec5-11e9-a9ca-4b564d003a74``. This UID should be queried by the
guest using the standard "Call UID" function for the service range in
order to determine that the KVM/arm64-specific hypercalls are available.
``ARM_SMCCC_VENDOR_HYP_KVM_FEATURES_FUNC_ID``
---------------------------------------------
Provides a discovery mechanism for other KVM/arm64 hypercalls.
+---------------------+-------------------------------------------------------------+
| Presence: | Mandatory for the KVM/arm64 UID |
+---------------------+-------------------------------------------------------------+
| Calling convention: | HVC32 |
+---------------------+----------+--------------------------------------------------+
| Function ID: | (uint32) | 0x86000000 |
+---------------------+----------+--------------------------------------------------+
| Arguments: | None |
+---------------------+----------+----+---------------------------------------------+
| Return Values: | (uint32) | R0 | Bitmap of available function numbers 0-31 |
| +----------+----+---------------------------------------------+
| | (uint32) | R1 | Bitmap of available function numbers 32-63 |
| +----------+----+---------------------------------------------+
| | (uint32) | R2 | Bitmap of available function numbers 64-95 |
| +----------+----+---------------------------------------------+
| | (uint32) | R3 | Bitmap of available function numbers 96-127 |
+---------------------+----------+----+---------------------------------------------+
``ARM_SMCCC_VENDOR_HYP_KVM_PTP_FUNC_ID``
----------------------------------------
See ptp_kvm.rst
pKVM memory protection hypercall
48-145다음 HVC64 call은 pKVM protected guest에서만 선택적으로 제공됩니다. Memory operation의 단위는 `ARM_SMCCC_KVM_FUNC_HYP_MEMINFO`가 반환하는 protection granule이며 reserved argument는 반드시 0이어야 합니다.
FunctionID와 계약
`ARM_SMCCC_KVM_FUNC_HYP_MEMINFO``0xC6000002`; R1-R3=0. 성공 시 R0=memory protection granule bytes, 오류 `INVALID_PARAMETER (-3)`
`ARM_SMCCC_KVM_FUNC_MEM_SHARE``0xC6000003`; R1=공유할 region의 base IPA, R2-R3=0. Host에 read·write·execute permission 부여
`ARM_SMCCC_KVM_FUNC_MEM_UNSHARE``0xC6000004`; R1=이전에 공유한 region의 base IPA, R2-R3=0. Host access permission 회수
`ARM_SMCCC_KVM_FUNC_MMIO_GUARD``0xC6000007`; R1=MMIO region base IPA, R2-R3=0. Host가 access를 emulate하도록 MMIO 취급 요청
Protected guest와 host 사이의 memory 접근 권한을 granule 단위로 관리합니다.
SHARE, UNSHARE, MMIO_GUARD의 정상 반환값은 `SUCCESS (0)`이고 잘못된 parameter는 `INVALID_PARAMETER (-3)`입니다. Base IPA와 range는 MEMINFO가 광고한 granule alignment와 크기 계약을 따라야 합니다.
HYP_MEMINFO로 protection granule 조회→Granule-aligned IPA 선택→MEM_SHARE로 host R/W/X 허용 또는 MMIO_GUARD로 emulation 요청→사용 종료 뒤 MEM_UNSHARE로 host permission 회수
Guest가 host access를 명시적으로 열고 닫습니다.
``ARM_SMCCC_KVM_FUNC_HYP_MEMINFO``
----------------------------------
Query the memory protection parameters for a pKVM protected virtual machine.
+---------------------+-------------------------------------------------------------+
| Presence: | Optional; pKVM protected guests only. |
+---------------------+-------------------------------------------------------------+
| Calling convention: | HVC64 |
+---------------------+----------+--------------------------------------------------+
| Function ID: | (uint32) | 0xC6000002 |
+---------------------+----------+----+---------------------------------------------+
| Arguments: | (uint64) | R1 | Reserved / Must be zero |
| +----------+----+---------------------------------------------+
| | (uint64) | R2 | Reserved / Must be zero |
| +----------+----+---------------------------------------------+
| | (uint64) | R3 | Reserved / Must be zero |
+---------------------+----------+----+---------------------------------------------+
| Return Values: | (int64) | R0 | ``INVALID_PARAMETER (-3)`` on error, else |
| | | | memory protection granule in bytes |
+---------------------+----------+----+---------------------------------------------+
``ARM_SMCCC_KVM_FUNC_MEM_SHARE``
--------------------------------
Share a region of memory with the KVM host, granting it read, write and execute
permissions. The size of the region is equal to the memory protection granule
advertised by ``ARM_SMCCC_KVM_FUNC_HYP_MEMINFO``.
+---------------------+-------------------------------------------------------------+
| Presence: | Optional; pKVM protected guests only. |
+---------------------+-------------------------------------------------------------+
| Calling convention: | HVC64 |
+---------------------+----------+--------------------------------------------------+
| Function ID: | (uint32) | 0xC6000003 |
+---------------------+----------+----+---------------------------------------------+
| Arguments: | (uint64) | R1 | Base IPA of memory region to share |
| +----------+----+---------------------------------------------+
| | (uint64) | R2 | Reserved / Must be zero |
| +----------+----+---------------------------------------------+
| | (uint64) | R3 | Reserved / Must be zero |
+---------------------+----------+----+---------------------------------------------+
| Return Values: | (int64) | R0 | ``SUCCESS (0)`` |
| | | +---------------------------------------------+
| | | | ``INVALID_PARAMETER (-3)`` |
+---------------------+----------+----+---------------------------------------------+
``ARM_SMCCC_KVM_FUNC_MEM_UNSHARE``
----------------------------------
Revoke access permission from the KVM host to a memory region previously shared
with ``ARM_SMCCC_KVM_FUNC_MEM_SHARE``. The size of the region is equal to the
memory protection granule advertised by ``ARM_SMCCC_KVM_FUNC_HYP_MEMINFO``.
+---------------------+-------------------------------------------------------------+
| Presence: | Optional; pKVM protected guests only. |
+---------------------+-------------------------------------------------------------+
| Calling convention: | HVC64 |
+---------------------+----------+--------------------------------------------------+
| Function ID: | (uint32) | 0xC6000004 |
+---------------------+----------+----+---------------------------------------------+
| Arguments: | (uint64) | R1 | Base IPA of memory region to unshare |
| +----------+----+---------------------------------------------+
| | (uint64) | R2 | Reserved / Must be zero |
| +----------+----+---------------------------------------------+
| | (uint64) | R3 | Reserved / Must be zero |
+---------------------+----------+----+---------------------------------------------+
| Return Values: | (int64) | R0 | ``SUCCESS (0)`` |
| | | +---------------------------------------------+
| | | | ``INVALID_PARAMETER (-3)`` |
+---------------------+----------+----+---------------------------------------------+
``ARM_SMCCC_KVM_FUNC_MMIO_GUARD``
----------------------------------
Request that a given memory region is handled as MMIO by the hypervisor,
allowing accesses to this region to be emulated by the KVM host. The size of the
region is equal to the memory protection granule advertised by
``ARM_SMCCC_KVM_FUNC_HYP_MEMINFO``.
+---------------------+-------------------------------------------------------------+
| Presence: | Optional; pKVM protected guests only. |
+---------------------+-------------------------------------------------------------+
| Calling convention: | HVC64 |
+---------------------+----------+--------------------------------------------------+
| Function ID: | (uint32) | 0xC6000007 |
+---------------------+----------+----+---------------------------------------------+
| Arguments: | (uint64) | R1 | Base IPA of MMIO memory region |
| +----------+----+---------------------------------------------+
| | (uint64) | R2 | Reserved / Must be zero |
| +----------+----+---------------------------------------------+
| | (uint64) | R3 | Reserved / Must be zero |
+---------------------+----------+----+---------------------------------------------+
| Return Values: | (int64) | R0 | ``SUCCESS (0)`` |
| | | +---------------------------------------------+
| | | | ``INVALID_PARAMETER (-3)`` |
+---------------------+----------+----+---------------------------------------------+
Target CPU implementation discovery
146-203KVM/arm64 guest는 선택적인 HVC64 discovery call로 target CPU implementation version과 구현별 ID register를 얻을 수 있습니다. Guest kernel은 결과를 이용해 해당 CPU implementation의 errata 처리를 enable합니다.
Function입력과 반환
`ARM_SMCCC_VENDOR_HYP_KVM_DISCOVER_IMPL_VER_FUNC_ID`ID `0xC6000040`, argument 없음. R0=`SUCCESS (0)` 또는 `NOT_SUPPORTED (-1)`; R1[31:16]=major, R1[15:0]=minor, R1[63:32]=0; R2=구현 수; R3=0
`ARM_SMCCC_VENDOR_HYP_KVM_DISCOVER_IMPL_CPUS_FUNC_ID`ID `0xC6000041`; R1=implementation index, R2-R3=0. 성공 시 R1=`MIDR_EL1`, R2=`REVIDR_EL1`, R3=`AIDR_EL1`; 잘못된 index는 `INVALID_PARAMETER (-3)`
Version을 조회한 뒤 구현 index별 CPU ID를 읽습니다.
Userspace가 firmware pseudo-register의 `DISCOVER_IMPL_VER`와 `DISCOVER_IMPL_CPUS` bit를 guest에 노출한 경우에만 guest가 이 ABI를 사용할 수 있습니다. Version query가 반환한 target implementation 수를 넘는 index를 CPU query에 전달해서는 안 됩니다.
``ARM_SMCCC_VENDOR_HYP_KVM_DISCOVER_IMPL_VER_FUNC_ID``
-------------------------------------------------------
Request the target CPU implementation version information and the number of target
implementations for the Guest VM.
+---------------------+-------------------------------------------------------------+
| Presence: | Optional; KVM/ARM64 Guests only |
+---------------------+-------------------------------------------------------------+
| Calling convention: | HVC64 |
+---------------------+----------+--------------------------------------------------+
| Function ID: | (uint32) | 0xC6000040 |
+---------------------+----------+--------------------------------------------------+
| Arguments: | None |
+---------------------+----------+----+---------------------------------------------+
| Return Values: | (int64) | R0 | ``SUCCESS (0)`` |
| | | +---------------------------------------------+
| | | | ``NOT_SUPPORTED (-1)`` |
| +----------+----+---------------------------------------------+
| | (uint64) | R1 | Bits [63:32] Reserved/Must be zero |
| | | +---------------------------------------------+
| | | | Bits [31:16] Major version |
| | | +---------------------------------------------+
| | | | Bits [15:0] Minor version |
| +----------+----+---------------------------------------------+
| | (uint64) | R2 | Number of target implementations |
| +----------+----+---------------------------------------------+
| | (uint64) | R3 | Reserved / Must be zero |
+---------------------+----------+----+---------------------------------------------+
``ARM_SMCCC_VENDOR_HYP_KVM_DISCOVER_IMPL_CPUS_FUNC_ID``
-------------------------------------------------------
Request the target CPU implementation information for the Guest VM. The Guest kernel
will use this information to enable the associated errata.
+---------------------+-------------------------------------------------------------+
| Presence: | Optional; KVM/ARM64 Guests only |
+---------------------+-------------------------------------------------------------+
| Calling convention: | HVC64 |
+---------------------+----------+--------------------------------------------------+
| Function ID: | (uint32) | 0xC6000041 |
+---------------------+----------+----+---------------------------------------------+
| Arguments: | (uint64) | R1 | selected implementation index |
| +----------+----+---------------------------------------------+
| | (uint64) | R2 | Reserved / Must be zero |
| +----------+----+---------------------------------------------+
| | (uint64) | R3 | Reserved / Must be zero |
+---------------------+----------+----+---------------------------------------------+
| Return Values: | (int64) | R0 | ``SUCCESS (0)`` |
| | | +---------------------------------------------+
| | | | ``INVALID_PARAMETER (-3)`` |
| +----------+----+---------------------------------------------+
| | (uint64) | R1 | MIDR_EL1 of the selected implementation |
| +----------+----+---------------------------------------------+
| | (uint64) | R2 | REVIDR_EL1 of the selected implementation |
| +----------+----+---------------------------------------------+
| | (uint64) | R3 | AIDR_EL1 of the selected implementation |
+---------------------+----------+----+---------------------------------------------+
요약·해설
hypercalls.rst:1-203KVM vendor UID와 feature discovery, pKVM memory share·unshare·MMIO guard 및 target CPU implementation discovery ABI입니다.
API 이름, register, function ID, source path와 error code는 원문 표기를 유지했습니다.