299 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 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.010 11Only one VGIC instance may be instantiated through this API. The created VGIC12will act as the VM interrupt controller, requiring emulated user-space devices13to inject interrupts to the VGIC instead of directly to CPUs. It is not14possible 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_ADDR21 Attributes:22 23 KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit)24 Base address in the guest physical address space of the GICv3 distributor25 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 GICv330 redistributor register mappings. There are two 64K pages for each31 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 - 039 values: | count | base | flags | index40 41 - index encodes the unique redistributor region index42 - flags: reserved for future use, currently 043 - base field encodes bits [51:16] of the guest physical base address44 of the first redistributor in the region.45 - count encodes the number of redistributors in the region. Must be46 greater than 0.47 48 There are two 64K pages for each redistributor in the region and49 redistributors are laid out contiguously within the region. Regions50 are filled with redistributors in the index order. The sum of all51 region count fields must be greater than or equal to the number of52 VCPUs. Redistributor regions must be registered in the incremental53 index order, starting from index 0.54 55 The characteristics of a specific redistributor region can be read56 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 and60 KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes.61 62 Note that to obtain reproducible results (the same VCPU being associated63 with the same redistributor across a save/restore operation), VCPU creation64 order, redistributor region creation order as well as the respective65 interleaves of VCPU and region creation MUST be preserved. Any change in66 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 range73 -EINVAL Incorrectly aligned address, bad redistributor region74 count/index, mixed redistributor region attribute usage75 -EEXIST Address already configured76 -ENOENT Attempt to read the characteristics of a non existing77 redistributor region78 -ENXIO The group or attribute is unknown/unsupported for this device79 or hardware support is missing.80 -EFAULT Invalid user pointer for attr->addr.81 ======= =============================================================82 83 84 KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS85 Attributes:86 87 The attr field of kvm_device_attr encodes two values::88 89 bits: | 63 .... 32 | 31 .... 0 |90 values: | mpidr | offset |91 92 All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a93 __u32 value. 64-bit registers must be accessed by separately accessing the94 lower and higher word.95 96 Writes to read-only registers are ignored by the kernel.97 98 KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers.99 KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU100 specified by the mpidr.101 102 The offset is relative to the "[Re]Distributor base address" as defined103 in the GICv3/4 specs. Getting or setting such a register has the same104 effect as reading or writing the register on real hardware, except for the105 following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR,106 GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0. These registers behave107 differently when accessed via this interface compared to their108 architecturally defined behavior to allow software a full view of the109 VGIC's internal state.110 111 The mpidr field is used to specify which112 redistributor is accessed. The mpidr is ignored for the distributor.113 114 The mpidr encoding is based on the affinity information in the115 architecture defined MPIDR, and the field is encoded as follows::116 117 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |118 | Aff3 | Aff2 | Aff1 | Aff0 |119 120 Note that distributor fields are not banked, but return the same value121 regardless of the mpidr used to access the register.122 123 GICD_IIDR.Revision is updated when the KVM implementation is changed in a124 way directly observable by the guest or userspace. Userspace should read125 GICD_IIDR from KVM and write back the read value to confirm its expected126 behavior is aligned with the KVM implementation. Userspace should set127 GICD_IIDR before setting any other registers to ensure the expected128 behavior.129 130 131 The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such132 that a write of a clear bit has no effect, whereas a write with a set bit133 clears that value. To allow userspace to freely set the values of these two134 registers, setting the attributes with the register offsets for these two135 registers simply sets the non-reserved bits to the value written.136 137 138 Accesses (reads and writes) to the GICD_ISPENDR register region and139 GICR_ISPENDR0 registers get/set the value of the latched pending state for140 the interrupts.141 142 This is identical to the value returned by a guest read from ISPENDR for an143 edge triggered interrupt, but may differ for level triggered interrupts.144 For edge triggered interrupts, once an interrupt becomes pending (whether145 because of an edge detected on the input line or because of a guest write146 to ISPENDR) this state is "latched", and only cleared when either the147 interrupt is activated or when the guest writes to ICPENDR. A level148 triggered interrupt may be pending either because the level input is held149 high by a device, or because of a guest write to the ISPENDR register. Only150 ISPENDR writes are latched; if the device lowers the line level then the151 interrupt is no longer pending unless the guest also wrote to ISPENDR, and152 conversely writes to ICPENDR or activations of the interrupt do not clear153 the pending status if the line level is still being held high. (These154 rules are documented in the GICv3 specification descriptions of the ICPENDR155 and ISPENDR registers.) For a level triggered interrupt the value accessed156 here is that of the latch which is set by ISPENDR and cleared by ICPENDR or157 interrupt activation, whereas the value returned by a guest read from158 ISPENDR is the logical OR of the latch value and the input line level.159 160 Raw access to the latch state is provided to userspace so that it can save161 and restore the entire GIC internal state (which is defined by the162 combination of the current input line level and the latch state, and cannot163 be deduced from purely the line level and the value of the ISPENDR164 registers).165 166 Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have167 RAZ/WI semantics, meaning that reads always return 0 and writes are always168 ignored.169 170 Errors:171 172 ====== =====================================================173 -ENXIO Getting or setting this register is not yet supported174 -EBUSY One or more VCPUs are running175 ====== =====================================================176 177 178 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS179 Attributes:180 181 The attr field of kvm_device_attr encodes two values::182 183 bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 |184 values: | mpidr | RES | instr |185 186 The mpidr field encodes the CPU ID based on the affinity information in the187 architecture defined MPIDR, and the field is encoded as follows::188 189 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |190 | Aff3 | Aff2 | Aff1 | Aff0 |191 192 The instr field encodes the system register to access based on the fields193 defined in the A64 instruction set encoding for system register access194 (RES means the bits are reserved for future use and should be zero)::195 196 | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 |197 | Op 0 | Op1 | CRn | CRm | Op2 |198 199 All system regs accessed through this API are (rw, 64-bit) and200 kvm_device_attr.addr points to a __u64 value.201 202 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the203 CPU specified by the mpidr field.204 205 CPU interface registers access is not implemented for AArch32 mode.206 Error -ENXIO is returned when accessed in AArch32 mode.207 208 Errors:209 210 ======= =====================================================211 -ENXIO Getting or setting this register is not yet supported212 -EBUSY VCPU is running213 -EINVAL Invalid mpidr or register value supplied214 ======= =====================================================215 216 217 KVM_DEV_ARM_VGIC_GRP_NR_IRQS218 Attributes:219 220 A value describing the number of interrupts (SGI, PPI and SPI) for221 this GIC instance, ranging from 64 to 1024, in increments of 32.222 223 kvm_device_attr.addr points to a __u32 value.224 225 Errors:226 227 ======= ======================================228 -EINVAL Value set is out of the expected range229 -EBUSY Value has already be set.230 ======= ======================================231 232 233 KVM_DEV_ARM_VGIC_GRP_CTRL234 Attributes:235 236 KVM_DEV_ARM_VGIC_CTRL_INIT237 request the initialization of the VGIC, no additional parameter in238 kvm_device_attr.addr. Must be called after all VCPUs have been created.239 KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES240 save all LPI pending bits into guest RAM pending tables.241 242 The first kB of the pending table is not altered by this operation.243 244 Errors:245 246 ======= ========================================================247 -ENXIO VGIC not properly configured as required prior to calling248 this attribute249 -ENODEV no online VCPU250 -ENOMEM memory shortage when allocating vgic internal data251 -EFAULT Invalid guest ram access252 -EBUSY One or more VCPUS are running253 ======= ========================================================254 255 256 KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO257 Attributes:258 259 The attr field of kvm_device_attr encodes the following values::260 261 bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 |262 values: | mpidr | info | vINTID |263 264 The vINTID specifies which set of IRQs is reported on.265 266 The info field specifies which information userspace wants to get or set267 using this interface. Currently we support the following info values:268 269 VGIC_LEVEL_INFO_LINE_LEVEL:270 Get/Set the input level of the IRQ line for a set of 32 contiguously271 numbered interrupts.272 273 vINTID must be a multiple of 32.274 275 kvm_device_attr.addr points to a __u32 value which will contain a276 bitmap where a set bit means the interrupt level is asserted.277 278 Bit[n] indicates the status for interrupt vINTID + n.279 280 SGIs and any interrupt with a higher ID than the number of interrupts281 supported, will be RAZ/WI. LPIs are always edge-triggered and are282 therefore not supported by this interface.283 284 PPIs are reported per VCPU as specified in the mpidr field, and SPIs are285 reported with the same value regardless of the mpidr specified.286 287 The mpidr field encodes the CPU ID based on the affinity information in the288 architecture defined MPIDR, and the field is encoded as follows::289 290 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |291 | Aff3 | Aff2 | Aff1 | Aff0 |292 293 Errors:294 295 ======= =============================================296 -EINVAL vINTID is not multiple of 32 or info field is297 not VGIC_LEVEL_INFO_LINE_LEVEL298 ======= =============================================299