tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1.. SPDX-License-Identifier: GPL-2.0
2
3==============================================================
4ARM Virtual Generic Interrupt Controller v3 and later (VGICv3)
5==============================================================
6
7
8Device types supported:
9 - KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0
10
11Only one VGIC instance may be instantiated through this API. The created VGIC
12will act as the VM interrupt controller, requiring emulated user-space devices
13to inject interrupts to the VGIC instead of directly to CPUs. It is not
14possible to create both a GICv3 and GICv2 on the same VM.
15
16Creating a guest GICv3 device requires a host GICv3 host, or a GICv5 host with
17support for FEAT_GCIE_LEGACY.
18
19
20Groups:
21 KVM_DEV_ARM_VGIC_GRP_ADDR
22 Attributes:
23
24 KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit)
25 Base address in the guest physical address space of the GICv3 distributor
26 register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
27 This address needs to be 64K aligned and the region covers 64 KByte.
28
29 KVM_VGIC_V3_ADDR_TYPE_REDIST (rw, 64-bit)
30 Base address in the guest physical address space of the GICv3
31 redistributor register mappings. There are two 64K pages for each
32 VCPU and all of the redistributor pages are contiguous.
33 Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
34 This address needs to be 64K aligned.
35
36 KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION (rw, 64-bit)
37 The attribute data pointed to by kvm_device_attr.addr is a __u64 value::
38
39 bits: | 63 .... 52 | 51 .... 16 | 15 - 12 |11 - 0
40 values: | count | base | flags | index
41
42 - index encodes the unique redistributor region index
43 - flags: reserved for future use, currently 0
44 - base field encodes bits [51:16] of the guest physical base address
45 of the first redistributor in the region.
46 - count encodes the number of redistributors in the region. Must be
47 greater than 0.
48
49 There are two 64K pages for each redistributor in the region and
50 redistributors are laid out contiguously within the region. Regions
51 are filled with redistributors in the index order. The sum of all
52 region count fields must be greater than or equal to the number of
53 VCPUs. Redistributor regions must be registered in the incremental
54 index order, starting from index 0.
55
56 The characteristics of a specific redistributor region can be read
57 by presetting the index field in the attr data.
58 Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
59
60 It is invalid to mix calls with KVM_VGIC_V3_ADDR_TYPE_REDIST and
61 KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes.
62
63 Note that to obtain reproducible results (the same VCPU being associated
64 with the same redistributor across a save/restore operation), VCPU creation
65 order, redistributor region creation order as well as the respective
66 interleaves of VCPU and region creation MUST be preserved. Any change in
67 either ordering may result in a different vcpu_id/redistributor association,
68 resulting in a VM that will fail to run at restore time.
69
70 Errors:
71
72 ======= =============================================================
73 -E2BIG Address outside of addressable IPA range
74 -EINVAL Incorrectly aligned address, bad redistributor region
75 count/index, mixed redistributor region attribute usage
76 -EEXIST Address already configured
77 -ENOENT Attempt to read the characteristics of a non existing
78 redistributor region
79 -ENXIO The group or attribute is unknown/unsupported for this device
80 or hardware support is missing.
81 -EFAULT Invalid user pointer for attr->addr.
82 -EBUSY Attempt to write a register that is read-only after
83 initialization
84 ======= =============================================================
85
86
87 KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS
88 Attributes:
89
90 The attr field of kvm_device_attr encodes two values::
91
92 bits: | 63 .... 32 | 31 .... 0 |
93 values: | mpidr | offset |
94
95 All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a
96 __u32 value. 64-bit registers must be accessed by separately accessing the
97 lower and higher word.
98
99 Writes to read-only registers are ignored by the kernel.
100
101 KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers.
102 KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU
103 specified by the mpidr.
104
105 The offset is relative to the "[Re]Distributor base address" as defined
106 in the GICv3/4 specs. Getting or setting such a register has the same
107 effect as reading or writing the register on real hardware, except for the
108 following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR,
109 GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0. These registers behave
110 differently when accessed via this interface compared to their
111 architecturally defined behavior to allow software a full view of the
112 VGIC's internal state.
113
114 The mpidr field is used to specify which
115 redistributor is accessed. The mpidr is ignored for the distributor.
116
117 The mpidr encoding is based on the affinity information in the
118 architecture defined MPIDR, and the field is encoded as follows::
119
120 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
121 | Aff3 | Aff2 | Aff1 | Aff0 |
122
123 Note that distributor fields are not banked, but return the same value
124 regardless of the mpidr used to access the register.
125
126 Userspace is allowed to write the following register fields prior to
127 initialization of the VGIC:
128
129 * GICD_IIDR.Revision
130 * GICD_TYPER2.nASSGIcap
131
132 GICD_IIDR.Revision is updated when the KVM implementation is changed in a
133 way directly observable by the guest or userspace. Userspace should read
134 GICD_IIDR from KVM and write back the read value to confirm its expected
135 behavior is aligned with the KVM implementation. Userspace should set
136 GICD_IIDR before setting any other registers to ensure the expected
137 behavior.
138
139
140 GICD_TYPER2.nASSGIcap allows userspace to control the support of SGIs
141 without an active state. At VGIC creation the field resets to the
142 maximum capability of the system. Userspace is expected to read the field
143 to determine the supported value(s) before writing to the field.
144
145
146 The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such
147 that a write of a clear bit has no effect, whereas a write with a set bit
148 clears that value. To allow userspace to freely set the values of these two
149 registers, setting the attributes with the register offsets for these two
150 registers simply sets the non-reserved bits to the value written.
151
152
153 Accesses (reads and writes) to the GICD_ISPENDR register region and
154 GICR_ISPENDR0 registers get/set the value of the latched pending state for
155 the interrupts.
156
157 This is identical to the value returned by a guest read from ISPENDR for an
158 edge triggered interrupt, but may differ for level triggered interrupts.
159 For edge triggered interrupts, once an interrupt becomes pending (whether
160 because of an edge detected on the input line or because of a guest write
161 to ISPENDR) this state is "latched", and only cleared when either the
162 interrupt is activated or when the guest writes to ICPENDR. A level
163 triggered interrupt may be pending either because the level input is held
164 high by a device, or because of a guest write to the ISPENDR register. Only
165 ISPENDR writes are latched; if the device lowers the line level then the
166 interrupt is no longer pending unless the guest also wrote to ISPENDR, and
167 conversely writes to ICPENDR or activations of the interrupt do not clear
168 the pending status if the line level is still being held high. (These
169 rules are documented in the GICv3 specification descriptions of the ICPENDR
170 and ISPENDR registers.) For a level triggered interrupt the value accessed
171 here is that of the latch which is set by ISPENDR and cleared by ICPENDR or
172 interrupt activation, whereas the value returned by a guest read from
173 ISPENDR is the logical OR of the latch value and the input line level.
174
175 Raw access to the latch state is provided to userspace so that it can save
176 and restore the entire GIC internal state (which is defined by the
177 combination of the current input line level and the latch state, and cannot
178 be deduced from purely the line level and the value of the ISPENDR
179 registers).
180
181 Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have
182 RAZ/WI semantics, meaning that reads always return 0 and writes are always
183 ignored.
184
185 Errors:
186
187 ====== =====================================================
188 -ENXIO Getting or setting this register is not yet supported
189 -EBUSY One or more VCPUs are running
190 ====== =====================================================
191
192
193 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS
194 Attributes:
195
196 The attr field of kvm_device_attr encodes two values::
197
198 bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 |
199 values: | mpidr | RES | instr |
200
201 The mpidr field encodes the CPU ID based on the affinity information in the
202 architecture defined MPIDR, and the field is encoded as follows::
203
204 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
205 | Aff3 | Aff2 | Aff1 | Aff0 |
206
207 The instr field encodes the system register to access based on the fields
208 defined in the A64 instruction set encoding for system register access
209 (RES means the bits are reserved for future use and should be zero)::
210
211 | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 |
212 | Op 0 | Op1 | CRn | CRm | Op2 |
213
214 All system regs accessed through this API are (rw, 64-bit) and
215 kvm_device_attr.addr points to a __u64 value.
216
217 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the
218 CPU specified by the mpidr field.
219
220 The available registers are:
221
222 =============== ====================================================
223 ICC_PMR_EL1
224 ICC_BPR0_EL1
225 ICC_AP0R0_EL1
226 ICC_AP0R1_EL1 when the host implements at least 6 bits of priority
227 ICC_AP0R2_EL1 when the host implements 7 bits of priority
228 ICC_AP0R3_EL1 when the host implements 7 bits of priority
229 ICC_AP1R0_EL1
230 ICC_AP1R1_EL1 when the host implements at least 6 bits of priority
231 ICC_AP1R2_EL1 when the host implements 7 bits of priority
232 ICC_AP1R3_EL1 when the host implements 7 bits of priority
233 ICC_BPR1_EL1
234 ICC_CTLR_EL1
235 ICC_SRE_EL1
236 ICC_IGRPEN0_EL1
237 ICC_IGRPEN1_EL1
238 =============== ====================================================
239
240 When EL2 is available for the guest, these registers are also available:
241
242 ============= ====================================================
243 ICH_AP0R0_EL2
244 ICH_AP0R1_EL2 when the host implements at least 6 bits of priority
245 ICH_AP0R2_EL2 when the host implements 7 bits of priority
246 ICH_AP0R3_EL2 when the host implements 7 bits of priority
247 ICH_AP1R0_EL2
248 ICH_AP1R1_EL2 when the host implements at least 6 bits of priority
249 ICH_AP1R2_EL2 when the host implements 7 bits of priority
250 ICH_AP1R3_EL2 when the host implements 7 bits of priority
251 ICH_HCR_EL2
252 ICC_SRE_EL2
253 ICH_VTR_EL2
254 ICH_VMCR_EL2
255 ICH_LR0_EL2
256 ICH_LR1_EL2
257 ICH_LR2_EL2
258 ICH_LR3_EL2
259 ICH_LR4_EL2
260 ICH_LR5_EL2
261 ICH_LR6_EL2
262 ICH_LR7_EL2
263 ICH_LR8_EL2
264 ICH_LR9_EL2
265 ICH_LR10_EL2
266 ICH_LR11_EL2
267 ICH_LR12_EL2
268 ICH_LR13_EL2
269 ICH_LR14_EL2
270 ICH_LR15_EL2
271 ============= ====================================================
272
273 CPU interface registers are only described using the AArch64
274 encoding.
275
276 Errors:
277
278 ======= =================================================
279 -ENXIO Getting or setting this register is not supported
280 -EBUSY VCPU is running
281 -EINVAL Invalid mpidr or register value supplied
282 ======= =================================================
283
284
285 KVM_DEV_ARM_VGIC_GRP_NR_IRQS
286 Attributes:
287
288 A value describing the number of interrupts (SGI, PPI and SPI) for
289 this GIC instance, ranging from 64 to 1024, in increments of 32.
290
291 kvm_device_attr.addr points to a __u32 value.
292
293 Errors:
294
295 ======= ======================================
296 -EINVAL Value set is out of the expected range
297 -EBUSY Value has already be set.
298 ======= ======================================
299
300
301 KVM_DEV_ARM_VGIC_GRP_CTRL
302 Attributes:
303
304 KVM_DEV_ARM_VGIC_CTRL_INIT
305 request the initialization of the VGIC, no additional parameter in
306 kvm_device_attr.addr. Must be called after all VCPUs have been created.
307 KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES
308 save all LPI pending bits into guest RAM pending tables.
309
310 The first kB of the pending table is not altered by this operation.
311
312 Errors:
313
314 ======= ========================================================
315 -ENXIO VGIC not properly configured as required prior to calling
316 this attribute
317 -ENODEV no online VCPU
318 -ENOMEM memory shortage when allocating vgic internal data
319 -EFAULT Invalid guest ram access
320 -EBUSY One or more VCPUS are running
321 ======= ========================================================
322
323
324 KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO
325 Attributes:
326
327 The attr field of kvm_device_attr encodes the following values::
328
329 bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 |
330 values: | mpidr | info | vINTID |
331
332 The vINTID specifies which set of IRQs is reported on.
333
334 The info field specifies which information userspace wants to get or set
335 using this interface. Currently we support the following info values:
336
337 VGIC_LEVEL_INFO_LINE_LEVEL:
338 Get/Set the input level of the IRQ line for a set of 32 contiguously
339 numbered interrupts.
340
341 vINTID must be a multiple of 32.
342
343 kvm_device_attr.addr points to a __u32 value which will contain a
344 bitmap where a set bit means the interrupt level is asserted.
345
346 Bit[n] indicates the status for interrupt vINTID + n.
347
348 SGIs and any interrupt with a higher ID than the number of interrupts
349 supported, will be RAZ/WI. LPIs are always edge-triggered and are
350 therefore not supported by this interface.
351
352 PPIs are reported per VCPU as specified in the mpidr field, and SPIs are
353 reported with the same value regardless of the mpidr specified.
354
355 The mpidr field encodes the CPU ID based on the affinity information in the
356 architecture defined MPIDR, and the field is encoded as follows::
357
358 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
359 | Aff3 | Aff2 | Aff1 | Aff0 |
360
361 Errors:
362 ======= =============================================
363 -EINVAL vINTID is not multiple of 32 or info field is
364 not VGIC_LEVEL_INFO_LINE_LEVEL
365 ======= =============================================
366
367 KVM_DEV_ARM_VGIC_GRP_MAINT_IRQ
368 Attributes:
369
370 The attr field of kvm_device_attr encodes the following values:
371
372 bits: | 31 .... 5 | 4 .... 0 |
373 values: | RES0 | vINTID |
374
375 The vINTID specifies which interrupt is generated when the vGIC
376 must generate a maintenance interrupt. This must be a PPI.