1ARM Virtual Generic Interrupt Controller v3 and later (VGICv3) 2============================================================== 3 4 5Device types supported: 6 KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0 7 8Only one VGIC instance may be instantiated through this API. The created VGIC 9will act as the VM interrupt controller, requiring emulated user-space devices 10to inject interrupts to the VGIC instead of directly to CPUs. It is not 11possible to create both a GICv3 and GICv2 on the same VM. 12 13Creating a guest GICv3 device requires a host GICv3 as well. 14 15 16Groups: 17 KVM_DEV_ARM_VGIC_GRP_ADDR 18 Attributes: 19 KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit) 20 Base address in the guest physical address space of the GICv3 distributor 21 register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3. 22 This address needs to be 64K aligned and the region covers 64 KByte. 23 24 KVM_VGIC_V3_ADDR_TYPE_REDIST (rw, 64-bit) 25 Base address in the guest physical address space of the GICv3 26 redistributor register mappings. There are two 64K pages for each 27 VCPU and all of the redistributor pages are contiguous. 28 Only valid for KVM_DEV_TYPE_ARM_VGIC_V3. 29 This address needs to be 64K aligned. 30 Errors: 31 -E2BIG: Address outside of addressable IPA range 32 -EINVAL: Incorrectly aligned address 33 -EEXIST: Address already configured 34 -ENXIO: The group or attribute is unknown/unsupported for this device 35 or hardware support is missing. 36 -EFAULT: Invalid user pointer for attr->addr. 37 38 39 40 KVM_DEV_ARM_VGIC_GRP_DIST_REGS 41 KVM_DEV_ARM_VGIC_GRP_REDIST_REGS 42 Attributes: 43 The attr field of kvm_device_attr encodes two values: 44 bits: | 63 .... 32 | 31 .... 0 | 45 values: | mpidr | offset | 46 47 All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a 48 __u32 value. 64-bit registers must be accessed by separately accessing the 49 lower and higher word. 50 51 Writes to read-only registers are ignored by the kernel. 52 53 KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers. 54 KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU 55 specified by the mpidr. 56 57 The offset is relative to the "[Re]Distributor base address" as defined 58 in the GICv3/4 specs. Getting or setting such a register has the same 59 effect as reading or writing the register on real hardware, except for the 60 following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR, 61 GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0. These registers behave 62 differently when accessed via this interface compared to their 63 architecturally defined behavior to allow software a full view of the 64 VGIC's internal state. 65 66 The mpidr field is used to specify which 67 redistributor is accessed. The mpidr is ignored for the distributor. 68 69 The mpidr encoding is based on the affinity information in the 70 architecture defined MPIDR, and the field is encoded as follows: 71 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | 72 | Aff3 | Aff2 | Aff1 | Aff0 | 73 74 Note that distributor fields are not banked, but return the same value 75 regardless of the mpidr used to access the register. 76 77 The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such 78 that a write of a clear bit has no effect, whereas a write with a set bit 79 clears that value. To allow userspace to freely set the values of these two 80 registers, setting the attributes with the register offsets for these two 81 registers simply sets the non-reserved bits to the value written. 82 83 84 Accesses (reads and writes) to the GICD_ISPENDR register region and 85 GICR_ISPENDR0 registers get/set the value of the latched pending state for 86 the interrupts. 87 88 This is identical to the value returned by a guest read from ISPENDR for an 89 edge triggered interrupt, but may differ for level triggered interrupts. 90 For edge triggered interrupts, once an interrupt becomes pending (whether 91 because of an edge detected on the input line or because of a guest write 92 to ISPENDR) this state is "latched", and only cleared when either the 93 interrupt is activated or when the guest writes to ICPENDR. A level 94 triggered interrupt may be pending either because the level input is held 95 high by a device, or because of a guest write to the ISPENDR register. Only 96 ISPENDR writes are latched; if the device lowers the line level then the 97 interrupt is no longer pending unless the guest also wrote to ISPENDR, and 98 conversely writes to ICPENDR or activations of the interrupt do not clear 99 the pending status if the line level is still being held high. (These 100 rules are documented in the GICv3 specification descriptions of the ICPENDR 101 and ISPENDR registers.) For a level triggered interrupt the value accessed 102 here is that of the latch which is set by ISPENDR and cleared by ICPENDR or 103 interrupt activation, whereas the value returned by a guest read from 104 ISPENDR is the logical OR of the latch value and the input line level. 105 106 Raw access to the latch state is provided to userspace so that it can save 107 and restore the entire GIC internal state (which is defined by the 108 combination of the current input line level and the latch state, and cannot 109 be deduced from purely the line level and the value of the ISPENDR 110 registers). 111 112 Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have 113 RAZ/WI semantics, meaning that reads always return 0 and writes are always 114 ignored. 115 116 Errors: 117 -ENXIO: Getting or setting this register is not yet supported 118 -EBUSY: One or more VCPUs are running 119 120 121 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS 122 Attributes: 123 The attr field of kvm_device_attr encodes two values: 124 bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 | 125 values: | mpidr | RES | instr | 126 127 The mpidr field encodes the CPU ID based on the affinity information in the 128 architecture defined MPIDR, and the field is encoded as follows: 129 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | 130 | Aff3 | Aff2 | Aff1 | Aff0 | 131 132 The instr field encodes the system register to access based on the fields 133 defined in the A64 instruction set encoding for system register access 134 (RES means the bits are reserved for future use and should be zero): 135 136 | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 | 137 | Op 0 | Op1 | CRn | CRm | Op2 | 138 139 All system regs accessed through this API are (rw, 64-bit) and 140 kvm_device_attr.addr points to a __u64 value. 141 142 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the 143 CPU specified by the mpidr field. 144 145 CPU interface registers access is not implemented for AArch32 mode. 146 Error -ENXIO is returned when accessed in AArch32 mode. 147 Errors: 148 -ENXIO: Getting or setting this register is not yet supported 149 -EBUSY: VCPU is running 150 -EINVAL: Invalid mpidr or register value supplied 151 152 153 KVM_DEV_ARM_VGIC_GRP_NR_IRQS 154 Attributes: 155 A value describing the number of interrupts (SGI, PPI and SPI) for 156 this GIC instance, ranging from 64 to 1024, in increments of 32. 157 158 kvm_device_attr.addr points to a __u32 value. 159 160 Errors: 161 -EINVAL: Value set is out of the expected range 162 -EBUSY: Value has already be set. 163 164 165 KVM_DEV_ARM_VGIC_GRP_CTRL 166 Attributes: 167 KVM_DEV_ARM_VGIC_CTRL_INIT 168 request the initialization of the VGIC, no additional parameter in 169 kvm_device_attr.addr. 170 KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES 171 save all LPI pending bits into guest RAM pending tables. 172 173 The first kB of the pending table is not altered by this operation. 174 Errors: 175 -ENXIO: VGIC not properly configured as required prior to calling 176 this attribute 177 -ENODEV: no online VCPU 178 -ENOMEM: memory shortage when allocating vgic internal data 179 -EFAULT: Invalid guest ram access 180 -EBUSY: One or more VCPUS are running 181 182 183 KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO 184 Attributes: 185 The attr field of kvm_device_attr encodes the following values: 186 bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 | 187 values: | mpidr | info | vINTID | 188 189 The vINTID specifies which set of IRQs is reported on. 190 191 The info field specifies which information userspace wants to get or set 192 using this interface. Currently we support the following info values: 193 194 VGIC_LEVEL_INFO_LINE_LEVEL: 195 Get/Set the input level of the IRQ line for a set of 32 contiguously 196 numbered interrupts. 197 vINTID must be a multiple of 32. 198 199 kvm_device_attr.addr points to a __u32 value which will contain a 200 bitmap where a set bit means the interrupt level is asserted. 201 202 Bit[n] indicates the status for interrupt vINTID + n. 203 204 SGIs and any interrupt with a higher ID than the number of interrupts 205 supported, will be RAZ/WI. LPIs are always edge-triggered and are 206 therefore not supported by this interface. 207 208 PPIs are reported per VCPU as specified in the mpidr field, and SPIs are 209 reported with the same value regardless of the mpidr specified. 210 211 The mpidr field encodes the CPU ID based on the affinity information in the 212 architecture defined MPIDR, and the field is encoded as follows: 213 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | 214 | Aff3 | Aff2 | Aff1 | Aff0 | 215 Errors: 216 -EINVAL: vINTID is not multiple of 32 or 217 info field is not VGIC_LEVEL_INFO_LINE_LEVEL 218