요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
==================================================
4
ARM Virtual Generic Interrupt Controller v2 (VGIC)
5
==================================================
7
Device types supported:
9
- KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0
11
Only one VGIC instance may be instantiated through either this API or the
12
legacy KVM_CREATE_IRQCHIP API. The created VGIC will act as the VM interrupt
13
controller, requiring emulated user-space devices to inject interrupts to the
14
VGIC instead of directly to CPUs.
16
GICv3 implementations with hardware compatibility support allow creating a
17
guest GICv2 through this interface. For information on creating a guest GICv3
18
device and guest ITS devices, see arm-vgic-v3.txt. It is not possible to
19
create both a GICv3 and GICv2 device on the same VM.
22
Groups:
23
KVM_DEV_ARM_VGIC_GRP_ADDR
24
Attributes:
26
KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit)
27
Base address in the guest physical address space of the GIC distributor
28
register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
29
This address needs to be 4K aligned and the region covers 4 KByte.
31
KVM_VGIC_V2_ADDR_TYPE_CPU (rw, 64-bit)
32
Base address in the guest physical address space of the GIC virtual cpu
33
interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
34
This address needs to be 4K aligned and the region covers 8 KByte.
36
Errors:
38
======= =============================================================
39
-E2BIG Address outside of addressable IPA range
40
-EINVAL Incorrectly aligned address
41
-EEXIST Address already configured
42
-ENXIO The group or attribute is unknown/unsupported for this device
43
or hardware support is missing.
44
-EFAULT Invalid user pointer for attr->addr.
45
======= =============================================================
47
KVM_DEV_ARM_VGIC_GRP_DIST_REGS
48
Attributes:
50
The attr field of kvm_device_attr encodes two values::
52
bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 |
53
values: | reserved | vcpu_index | offset |
55
All distributor regs are (rw, 32-bit)
57
The offset is relative to the "Distributor base address" as defined in the
58
GICv2 specs. Getting or setting such a register has the same effect as
59
reading or writing the register on the actual hardware from the cpu whose
60
index is specified with the vcpu_index field. Note that most distributor
61
fields are not banked, but return the same value regardless of the
62
vcpu_index used to access the register.
64
GICD_IIDR.Revision is updated when the KVM implementation of an emulated
65
GICv2 is changed in a way directly observable by the guest or userspace.
66
Userspace should read GICD_IIDR from KVM and write back the read value to
67
confirm its expected behavior is aligned with the KVM implementation.
68
Userspace should set GICD_IIDR before setting any other registers (both
69
KVM_DEV_ARM_VGIC_GRP_DIST_REGS and KVM_DEV_ARM_VGIC_GRP_CPU_REGS) to ensure
70
the expected behavior. Unless GICD_IIDR has been set from userspace, writes
71
to the interrupt group registers (GICD_IGROUPR) are ignored.
73
Errors:
75
======= =====================================================
76
-ENXIO Getting or setting this register is not yet supported
77
-EBUSY One or more VCPUs are running
78
-EINVAL Invalid vcpu_index supplied
79
======= =====================================================
81
KVM_DEV_ARM_VGIC_GRP_CPU_REGS
82
Attributes:
84
The attr field of kvm_device_attr encodes two values::
86
bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 |
87
values: | reserved | vcpu_index | offset |
89
All CPU interface regs are (rw, 32-bit)
91
The offset specifies the offset from the "CPU interface base address" as
92
defined in the GICv2 specs. Getting or setting such a register has the
93
same effect as reading or writing the register on the actual hardware.
95
The Active Priorities Registers APRn are implementation defined, so we set a
96
fixed format for our implementation that fits with the model of a "GICv2
97
implementation without the security extensions" which we present to the
98
guest. This interface always exposes four register APR[0-3] describing the
99
maximum possible 128 preemption levels. The semantics of the register
100
indicate if any interrupts in a given preemption level are in the active
101
state by setting the corresponding bit.
103
Thus, preemption level X has one or more active interrupts if and only if:
105
APRn[X mod 32] == 0b1, where n = X / 32
107
Bits for undefined preemption levels are RAZ/WI.
109
Note that this differs from a CPU's view of the APRs on hardware in which
110
a GIC without the security extensions expose group 0 and group 1 active
111
priorities in separate register groups, whereas we show a combined view
112
similar to GICv2's GICH_APR.
114
For historical reasons and to provide ABI compatibility with userspace we
115
export the GICC_PMR register in the format of the GICH_VMCR.VMPriMask
116
field in the lower 5 bits of a word, meaning that userspace must always
117
use the lower 5 bits to communicate with the KVM device and must shift the
118
value left by 3 places to obtain the actual priority mask level.
120
Errors:
122
======= =====================================================
123
-ENXIO Getting or setting this register is not yet supported
124
-EBUSY One or more VCPUs are running
125
-EINVAL Invalid vcpu_index supplied
126
======= =====================================================
128
KVM_DEV_ARM_VGIC_GRP_NR_IRQS
129
Attributes:
131
A value describing the number of interrupts (SGI, PPI and SPI) for
132
this GIC instance, ranging from 64 to 1024, in increments of 32.
134
Errors:
136
======= =============================================================
137
-EINVAL Value set is out of the expected range
138
-EBUSY Value has already be set, or GIC has already been initialized
139
with default values.
140
======= =============================================================
142
KVM_DEV_ARM_VGIC_GRP_CTRL
143
Attributes:
145
KVM_DEV_ARM_VGIC_CTRL_INIT
146
request the initialization of the VGIC or ITS, no additional parameter
147
in kvm_device_attr.addr.
149
Errors:
151
======= =========================================================
152
-ENXIO VGIC not properly configured as required prior to calling
153
this attribute
154
-ENODEV no online VCPU
155
-ENOMEM memory shortage when allocating vgic internal data
156
======= =========================================================
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
VGICv2 device와 address
1-46`KVM_DEV_TYPE_ARM_VGIC_V2`는 guest GICv2.0 controller를 생성합니다. 이 API 또는 legacy `KVM_CREATE_IRQCHIP` 중 어느 방식이든 VM에는 VGIC 하나만 만들 수 있으며 userspace device는 CPU가 아니라 VGIC에 interrupt를 주입합니다.
Hardware compatibility를 지원하는 GICv3 implementation에서는 이 interface로 guest GICv2를 만들 수 있습니다. 같은 VM에 GICv2와 GICv3를 동시에 만들 수 없습니다.
AttributeAlignment·크기
`KVM_VGIC_V2_ADDR_TYPE_DIST`Distributor base, 4KiB aligned, 4KiB region
`KVM_VGIC_V2_ADDR_TYPE_CPU`Virtual CPU interface base, 4KiB aligned, 8KiB region
`KVM_DEV_ARM_VGIC_GRP_ADDR`의 두 MMIO region입니다.
Error조건
`-E2BIG`Addressable IPA range 밖
`-EINVAL`잘못된 alignment
`-EEXIST`이미 설정된 address
`-ENXIO`Unknown·unsupported group/attribute 또는 hardware support 없음
`-EFAULT`잘못된 `attr->addr`
Address 설정 오류입니다.
.. SPDX-License-Identifier: GPL-2.0
==================================================
ARM Virtual Generic Interrupt Controller v2 (VGIC)
==================================================
Device types supported:
- KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0
Only one VGIC instance may be instantiated through either this API or the
legacy KVM_CREATE_IRQCHIP API. The created VGIC will act as the VM interrupt
controller, requiring emulated user-space devices to inject interrupts to the
VGIC instead of directly to CPUs.
GICv3 implementations with hardware compatibility support allow creating a
guest GICv2 through this interface. For information on creating a guest GICv3
device and guest ITS devices, see arm-vgic-v3.txt. It is not possible to
create both a GICv3 and GICv2 device on the same VM.
Groups:
KVM_DEV_ARM_VGIC_GRP_ADDR
Attributes:
KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit)
Base address in the guest physical address space of the GIC distributor
register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
This address needs to be 4K aligned and the region covers 4 KByte.
KVM_VGIC_V2_ADDR_TYPE_CPU (rw, 64-bit)
Base address in the guest physical address space of the GIC virtual cpu
interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
This address needs to be 4K aligned and the region covers 8 KByte.
Errors:
======= =============================================================
-E2BIG Address outside of addressable IPA range
-EINVAL Incorrectly aligned address
-EEXIST Address already configured
-ENXIO The group or attribute is unknown/unsupported for this device
or hardware support is missing.
-EFAULT Invalid user pointer for attr->addr.
======= =============================================================
Distributor와 CPU interface register
47-127Distributor와 CPU register group의 `attr`은 bit 39:32에 `vcpu_index`, bit 31:0에 register offset을 두며 상위 bit 63:40은 reserved입니다. 모든 register는 read/write 32-bit입니다.
Distributor offset은 GICv2 Distributor base 기준입니다. Hardware에서 지정 vCPU가 access한 것과 같은 효과를 가지지만 대부분 field는 non-banked라 vCPU index와 무관하게 같은 값을 반환합니다.
`GICD_IIDR.Revision`은 emulated GICv2 behavior가 관찰 가능하게 변할 때 갱신됩니다. Userspace는 KVM 값을 읽어 다시 쓰고, distributor·CPU의 다른 register보다 먼저 IIDR을 설정해야 합니다. Userspace가 IIDR을 설정하기 전에는 `GICD_IGROUPR` write가 무시됩니다.
CPU interface offset은 GICv2 CPU-interface base 기준이며 real hardware와 같은 효과를 가집니다. KVM ABI는 security extension 없는 GICv2 model에 맞춘 고정 APR format을 사용합니다.
항목규칙
Register항상 `APR[0]`부터 `APR[3]`까지 4개
Level X register`n = X / 32`인 `APRn`
Level X bit`X mod 32` bit가 1이면 해당 level에 active interrupt 존재
Undefined levelRAZ/WI
최대 128개 preemption level의 active 상태를 APR[0-3]에 합쳐 노출합니다.
실제 security-extension 없는 GIC hardware는 group 0·1 active priority를 별도 register group으로 보이지만 이 ABI는 `GICH_APR`와 비슷한 combined view를 제공합니다.
Historical userspace ABI 때문에 `GICC_PMR`은 word 하위 5-bit의 `GICH_VMCR.VMPriMask` format으로 export됩니다. 실제 priority mask level을 얻으려면 userspace가 값을 왼쪽으로 3-bit shift해야 합니다.
Error조건
`-ENXIO`Register get/set 미지원
`-EBUSY`하나 이상의 vCPU 실행 중
`-EINVAL`잘못된 `vcpu_index`
Distributor·CPU group 공통 오류입니다.
KVM_DEV_ARM_VGIC_GRP_DIST_REGS
Attributes:
The attr field of kvm_device_attr encodes two values::
bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 |
values: | reserved | vcpu_index | offset |
All distributor regs are (rw, 32-bit)
The offset is relative to the "Distributor base address" as defined in the
GICv2 specs. Getting or setting such a register has the same effect as
reading or writing the register on the actual hardware from the cpu whose
index is specified with the vcpu_index field. Note that most distributor
fields are not banked, but return the same value regardless of the
vcpu_index used to access the register.
GICD_IIDR.Revision is updated when the KVM implementation of an emulated
GICv2 is changed in a way directly observable by the guest or userspace.
Userspace should read GICD_IIDR from KVM and write back the read value to
confirm its expected behavior is aligned with the KVM implementation.
Userspace should set GICD_IIDR before setting any other registers (both
KVM_DEV_ARM_VGIC_GRP_DIST_REGS and KVM_DEV_ARM_VGIC_GRP_CPU_REGS) to ensure
the expected behavior. Unless GICD_IIDR has been set from userspace, writes
to the interrupt group registers (GICD_IGROUPR) are ignored.
Errors:
======= =====================================================
-ENXIO Getting or setting this register is not yet supported
-EBUSY One or more VCPUs are running
-EINVAL Invalid vcpu_index supplied
======= =====================================================
KVM_DEV_ARM_VGIC_GRP_CPU_REGS
Attributes:
The attr field of kvm_device_attr encodes two values::
bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 |
values: | reserved | vcpu_index | offset |
All CPU interface regs are (rw, 32-bit)
The offset specifies the offset from the "CPU interface base address" as
defined in the GICv2 specs. Getting or setting such a register has the
same effect as reading or writing the register on the actual hardware.
The Active Priorities Registers APRn are implementation defined, so we set a
fixed format for our implementation that fits with the model of a "GICv2
implementation without the security extensions" which we present to the
guest. This interface always exposes four register APR[0-3] describing the
maximum possible 128 preemption levels. The semantics of the register
indicate if any interrupts in a given preemption level are in the active
state by setting the corresponding bit.
Thus, preemption level X has one or more active interrupts if and only if:
APRn[X mod 32] == 0b1, where n = X / 32
Bits for undefined preemption levels are RAZ/WI.
Note that this differs from a CPU's view of the APRs on hardware in which
a GIC without the security extensions expose group 0 and group 1 active
priorities in separate register groups, whereas we show a combined view
similar to GICv2's GICH_APR.
For historical reasons and to provide ABI compatibility with userspace we
export the GICC_PMR register in the format of the GICH_VMCR.VMPriMask
field in the lower 5 bits of a word, meaning that userspace must always
use the lower 5 bits to communicate with the KVM device and must shift the
value left by 3 places to obtain the actual priority mask level.
Errors:
======= =====================================================
-ENXIO Getting or setting this register is not yet supported
-EBUSY One or more VCPUs are running
-EINVAL Invalid vcpu_index supplied
======= =====================================================
Interrupt 수와 initialization
128-156`KVM_DEV_ARM_VGIC_GRP_NR_IRQS`는 SGI, PPI, SPI를 포함한 interrupt 수를 64~1024 범위에서 32 단위로 설정합니다. 범위 밖은 `-EINVAL`; 이미 값이 정해졌거나 GIC가 default로 초기화된 뒤에는 `-EBUSY`입니다.
`KVM_DEV_ARM_VGIC_GRP_CTRL`의 `KVM_DEV_ARM_VGIC_CTRL_INIT`은 추가 parameter 없이 VGIC 또는 ITS initialization을 요청합니다.
Error조건
`-ENXIO`필수 VGIC configuration 미완료
`-ENODEV`Online vCPU 없음
`-ENOMEM`Internal VGIC data allocation 실패
필수 configuration과 resource 오류입니다.
KVM_DEV_ARM_VGIC_GRP_NR_IRQS
Attributes:
A value describing the number of interrupts (SGI, PPI and SPI) for
this GIC instance, ranging from 64 to 1024, in increments of 32.
Errors:
======= =============================================================
-EINVAL Value set is out of the expected range
-EBUSY Value has already be set, or GIC has already been initialized
with default values.
======= =============================================================
KVM_DEV_ARM_VGIC_GRP_CTRL
Attributes:
KVM_DEV_ARM_VGIC_CTRL_INIT
request the initialization of the VGIC or ITS, no additional parameter
in kvm_device_attr.addr.
Errors:
======= =========================================================
-ENXIO VGIC not properly configured as required prior to calling
this attribute
-ENODEV no online VCPU
-ENOMEM memory shortage when allocating vgic internal data
======= =========================================================
요약·해설
arm-vgic.rst:1-156VGICv2 MMIO address, banked distributor·CPU register, APR·PMR format과 initialization ABI입니다.
Register, attribute, bit field, error code와 source path는 원문 표기를 유지했습니다.