arm-vgic-v3.rst (12553B)
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 Errors: 63 64 ======= ============================================================= 65 -E2BIG Address outside of addressable IPA range 66 -EINVAL Incorrectly aligned address, bad redistributor region 67 count/index, mixed redistributor region attribute usage 68 -EEXIST Address already configured 69 -ENOENT Attempt to read the characteristics of a non existing 70 redistributor region 71 -ENXIO The group or attribute is unknown/unsupported for this device 72 or hardware support is missing. 73 -EFAULT Invalid user pointer for attr->addr. 74 ======= ============================================================= 75 76 77 KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS 78 Attributes: 79 80 The attr field of kvm_device_attr encodes two values:: 81 82 bits: | 63 .... 32 | 31 .... 0 | 83 values: | mpidr | offset | 84 85 All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a 86 __u32 value. 64-bit registers must be accessed by separately accessing the 87 lower and higher word. 88 89 Writes to read-only registers are ignored by the kernel. 90 91 KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers. 92 KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU 93 specified by the mpidr. 94 95 The offset is relative to the "[Re]Distributor base address" as defined 96 in the GICv3/4 specs. Getting or setting such a register has the same 97 effect as reading or writing the register on real hardware, except for the 98 following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR, 99 GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0. These registers behave 100 differently when accessed via this interface compared to their 101 architecturally defined behavior to allow software a full view of the 102 VGIC's internal state. 103 104 The mpidr field is used to specify which 105 redistributor is accessed. The mpidr is ignored for the distributor. 106 107 The mpidr encoding is based on the affinity information in the 108 architecture defined MPIDR, and the field is encoded as follows:: 109 110 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | 111 | Aff3 | Aff2 | Aff1 | Aff0 | 112 113 Note that distributor fields are not banked, but return the same value 114 regardless of the mpidr used to access the register. 115 116 GICD_IIDR.Revision is updated when the KVM implementation is changed in a 117 way directly observable by the guest or userspace. Userspace should read 118 GICD_IIDR from KVM and write back the read value to confirm its expected 119 behavior is aligned with the KVM implementation. Userspace should set 120 GICD_IIDR before setting any other registers to ensure the expected 121 behavior. 122 123 124 The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such 125 that a write of a clear bit has no effect, whereas a write with a set bit 126 clears that value. To allow userspace to freely set the values of these two 127 registers, setting the attributes with the register offsets for these two 128 registers simply sets the non-reserved bits to the value written. 129 130 131 Accesses (reads and writes) to the GICD_ISPENDR register region and 132 GICR_ISPENDR0 registers get/set the value of the latched pending state for 133 the interrupts. 134 135 This is identical to the value returned by a guest read from ISPENDR for an 136 edge triggered interrupt, but may differ for level triggered interrupts. 137 For edge triggered interrupts, once an interrupt becomes pending (whether 138 because of an edge detected on the input line or because of a guest write 139 to ISPENDR) this state is "latched", and only cleared when either the 140 interrupt is activated or when the guest writes to ICPENDR. A level 141 triggered interrupt may be pending either because the level input is held 142 high by a device, or because of a guest write to the ISPENDR register. Only 143 ISPENDR writes are latched; if the device lowers the line level then the 144 interrupt is no longer pending unless the guest also wrote to ISPENDR, and 145 conversely writes to ICPENDR or activations of the interrupt do not clear 146 the pending status if the line level is still being held high. (These 147 rules are documented in the GICv3 specification descriptions of the ICPENDR 148 and ISPENDR registers.) For a level triggered interrupt the value accessed 149 here is that of the latch which is set by ISPENDR and cleared by ICPENDR or 150 interrupt activation, whereas the value returned by a guest read from 151 ISPENDR is the logical OR of the latch value and the input line level. 152 153 Raw access to the latch state is provided to userspace so that it can save 154 and restore the entire GIC internal state (which is defined by the 155 combination of the current input line level and the latch state, and cannot 156 be deduced from purely the line level and the value of the ISPENDR 157 registers). 158 159 Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have 160 RAZ/WI semantics, meaning that reads always return 0 and writes are always 161 ignored. 162 163 Errors: 164 165 ====== ===================================================== 166 -ENXIO Getting or setting this register is not yet supported 167 -EBUSY One or more VCPUs are running 168 ====== ===================================================== 169 170 171 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS 172 Attributes: 173 174 The attr field of kvm_device_attr encodes two values:: 175 176 bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 | 177 values: | mpidr | RES | instr | 178 179 The mpidr field encodes the CPU ID based on the affinity information in the 180 architecture defined MPIDR, and the field is encoded as follows:: 181 182 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | 183 | Aff3 | Aff2 | Aff1 | Aff0 | 184 185 The instr field encodes the system register to access based on the fields 186 defined in the A64 instruction set encoding for system register access 187 (RES means the bits are reserved for future use and should be zero):: 188 189 | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 | 190 | Op 0 | Op1 | CRn | CRm | Op2 | 191 192 All system regs accessed through this API are (rw, 64-bit) and 193 kvm_device_attr.addr points to a __u64 value. 194 195 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the 196 CPU specified by the mpidr field. 197 198 CPU interface registers access is not implemented for AArch32 mode. 199 Error -ENXIO is returned when accessed in AArch32 mode. 200 201 Errors: 202 203 ======= ===================================================== 204 -ENXIO Getting or setting this register is not yet supported 205 -EBUSY VCPU is running 206 -EINVAL Invalid mpidr or register value supplied 207 ======= ===================================================== 208 209 210 KVM_DEV_ARM_VGIC_GRP_NR_IRQS 211 Attributes: 212 213 A value describing the number of interrupts (SGI, PPI and SPI) for 214 this GIC instance, ranging from 64 to 1024, in increments of 32. 215 216 kvm_device_attr.addr points to a __u32 value. 217 218 Errors: 219 220 ======= ====================================== 221 -EINVAL Value set is out of the expected range 222 -EBUSY Value has already be set. 223 ======= ====================================== 224 225 226 KVM_DEV_ARM_VGIC_GRP_CTRL 227 Attributes: 228 229 KVM_DEV_ARM_VGIC_CTRL_INIT 230 request the initialization of the VGIC, no additional parameter in 231 kvm_device_attr.addr. Must be called after all VCPUs have been created. 232 KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES 233 save all LPI pending bits into guest RAM pending tables. 234 235 The first kB of the pending table is not altered by this operation. 236 237 Errors: 238 239 ======= ======================================================== 240 -ENXIO VGIC not properly configured as required prior to calling 241 this attribute 242 -ENODEV no online VCPU 243 -ENOMEM memory shortage when allocating vgic internal data 244 -EFAULT Invalid guest ram access 245 -EBUSY One or more VCPUS are running 246 ======= ======================================================== 247 248 249 KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO 250 Attributes: 251 252 The attr field of kvm_device_attr encodes the following values:: 253 254 bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 | 255 values: | mpidr | info | vINTID | 256 257 The vINTID specifies which set of IRQs is reported on. 258 259 The info field specifies which information userspace wants to get or set 260 using this interface. Currently we support the following info values: 261 262 VGIC_LEVEL_INFO_LINE_LEVEL: 263 Get/Set the input level of the IRQ line for a set of 32 contiguously 264 numbered interrupts. 265 266 vINTID must be a multiple of 32. 267 268 kvm_device_attr.addr points to a __u32 value which will contain a 269 bitmap where a set bit means the interrupt level is asserted. 270 271 Bit[n] indicates the status for interrupt vINTID + n. 272 273 SGIs and any interrupt with a higher ID than the number of interrupts 274 supported, will be RAZ/WI. LPIs are always edge-triggered and are 275 therefore not supported by this interface. 276 277 PPIs are reported per VCPU as specified in the mpidr field, and SPIs are 278 reported with the same value regardless of the mpidr specified. 279 280 The mpidr field encodes the CPU ID based on the affinity information in the 281 architecture defined MPIDR, and the field is encoded as follows:: 282 283 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | 284 | Aff3 | Aff2 | Aff1 | Aff0 | 285 286 Errors: 287 288 ======= ============================================= 289 -EINVAL vINTID is not multiple of 32 or info field is 290 not VGIC_LEVEL_INFO_LINE_LEVEL 291 ======= =============================================