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