1bf6154dbSMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2bf6154dbSMauro Carvalho Chehab 3bf6154dbSMauro Carvalho Chehab================================================== 4bf6154dbSMauro Carvalho ChehabARM Virtual Generic Interrupt Controller v2 (VGIC) 5bf6154dbSMauro Carvalho Chehab================================================== 6bf6154dbSMauro Carvalho Chehab 7bf6154dbSMauro Carvalho ChehabDevice types supported: 8bf6154dbSMauro Carvalho Chehab 9bf6154dbSMauro Carvalho Chehab - KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0 10bf6154dbSMauro Carvalho Chehab 11bf6154dbSMauro Carvalho ChehabOnly one VGIC instance may be instantiated through either this API or the 12bf6154dbSMauro Carvalho Chehablegacy KVM_CREATE_IRQCHIP API. The created VGIC will act as the VM interrupt 13bf6154dbSMauro Carvalho Chehabcontroller, requiring emulated user-space devices to inject interrupts to the 14bf6154dbSMauro Carvalho ChehabVGIC instead of directly to CPUs. 15bf6154dbSMauro Carvalho Chehab 16bf6154dbSMauro Carvalho ChehabGICv3 implementations with hardware compatibility support allow creating a 17bf6154dbSMauro Carvalho Chehabguest GICv2 through this interface. For information on creating a guest GICv3 18bf6154dbSMauro Carvalho Chehabdevice and guest ITS devices, see arm-vgic-v3.txt. It is not possible to 19bf6154dbSMauro Carvalho Chehabcreate both a GICv3 and GICv2 device on the same VM. 20bf6154dbSMauro Carvalho Chehab 21bf6154dbSMauro Carvalho Chehab 22bf6154dbSMauro Carvalho ChehabGroups: 23bf6154dbSMauro Carvalho Chehab KVM_DEV_ARM_VGIC_GRP_ADDR 24bf6154dbSMauro Carvalho Chehab Attributes: 25bf6154dbSMauro Carvalho Chehab 26bf6154dbSMauro Carvalho Chehab KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit) 27bf6154dbSMauro Carvalho Chehab Base address in the guest physical address space of the GIC distributor 28bf6154dbSMauro Carvalho Chehab register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2. 29bf6154dbSMauro Carvalho Chehab This address needs to be 4K aligned and the region covers 4 KByte. 30bf6154dbSMauro Carvalho Chehab 31bf6154dbSMauro Carvalho Chehab KVM_VGIC_V2_ADDR_TYPE_CPU (rw, 64-bit) 32bf6154dbSMauro Carvalho Chehab Base address in the guest physical address space of the GIC virtual cpu 33bf6154dbSMauro Carvalho Chehab interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2. 34*810ecbefSChangyuan Lyu This address needs to be 4K aligned and the region covers 8 KByte. 35bf6154dbSMauro Carvalho Chehab 36bf6154dbSMauro Carvalho Chehab Errors: 37bf6154dbSMauro Carvalho Chehab 38bf6154dbSMauro Carvalho Chehab ======= ============================================================= 39bf6154dbSMauro Carvalho Chehab -E2BIG Address outside of addressable IPA range 40bf6154dbSMauro Carvalho Chehab -EINVAL Incorrectly aligned address 41bf6154dbSMauro Carvalho Chehab -EEXIST Address already configured 42bf6154dbSMauro Carvalho Chehab -ENXIO The group or attribute is unknown/unsupported for this device 43bf6154dbSMauro Carvalho Chehab or hardware support is missing. 44bf6154dbSMauro Carvalho Chehab -EFAULT Invalid user pointer for attr->addr. 45bf6154dbSMauro Carvalho Chehab ======= ============================================================= 46bf6154dbSMauro Carvalho Chehab 47bf6154dbSMauro Carvalho Chehab KVM_DEV_ARM_VGIC_GRP_DIST_REGS 48bf6154dbSMauro Carvalho Chehab Attributes: 49bf6154dbSMauro Carvalho Chehab 50bf6154dbSMauro Carvalho Chehab The attr field of kvm_device_attr encodes two values:: 51bf6154dbSMauro Carvalho Chehab 52bf6154dbSMauro Carvalho Chehab bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | 53bf6154dbSMauro Carvalho Chehab values: | reserved | vcpu_index | offset | 54bf6154dbSMauro Carvalho Chehab 55bf6154dbSMauro Carvalho Chehab All distributor regs are (rw, 32-bit) 56bf6154dbSMauro Carvalho Chehab 57bf6154dbSMauro Carvalho Chehab The offset is relative to the "Distributor base address" as defined in the 58bf6154dbSMauro Carvalho Chehab GICv2 specs. Getting or setting such a register has the same effect as 59bf6154dbSMauro Carvalho Chehab reading or writing the register on the actual hardware from the cpu whose 60bf6154dbSMauro Carvalho Chehab index is specified with the vcpu_index field. Note that most distributor 61bf6154dbSMauro Carvalho Chehab fields are not banked, but return the same value regardless of the 62bf6154dbSMauro Carvalho Chehab vcpu_index used to access the register. 63bf6154dbSMauro Carvalho Chehab 64bf6154dbSMauro Carvalho Chehab GICD_IIDR.Revision is updated when the KVM implementation of an emulated 65bf6154dbSMauro Carvalho Chehab GICv2 is changed in a way directly observable by the guest or userspace. 66bf6154dbSMauro Carvalho Chehab Userspace should read GICD_IIDR from KVM and write back the read value to 67bf6154dbSMauro Carvalho Chehab confirm its expected behavior is aligned with the KVM implementation. 68bf6154dbSMauro Carvalho Chehab Userspace should set GICD_IIDR before setting any other registers (both 69bf6154dbSMauro Carvalho Chehab KVM_DEV_ARM_VGIC_GRP_DIST_REGS and KVM_DEV_ARM_VGIC_GRP_CPU_REGS) to ensure 70bf6154dbSMauro Carvalho Chehab the expected behavior. Unless GICD_IIDR has been set from userspace, writes 71bf6154dbSMauro Carvalho Chehab to the interrupt group registers (GICD_IGROUPR) are ignored. 72bf6154dbSMauro Carvalho Chehab 73bf6154dbSMauro Carvalho Chehab Errors: 74bf6154dbSMauro Carvalho Chehab 75bf6154dbSMauro Carvalho Chehab ======= ===================================================== 76bf6154dbSMauro Carvalho Chehab -ENXIO Getting or setting this register is not yet supported 77bf6154dbSMauro Carvalho Chehab -EBUSY One or more VCPUs are running 78bf6154dbSMauro Carvalho Chehab -EINVAL Invalid vcpu_index supplied 79bf6154dbSMauro Carvalho Chehab ======= ===================================================== 80bf6154dbSMauro Carvalho Chehab 81bf6154dbSMauro Carvalho Chehab KVM_DEV_ARM_VGIC_GRP_CPU_REGS 82bf6154dbSMauro Carvalho Chehab Attributes: 83bf6154dbSMauro Carvalho Chehab 84bf6154dbSMauro Carvalho Chehab The attr field of kvm_device_attr encodes two values:: 85bf6154dbSMauro Carvalho Chehab 86bf6154dbSMauro Carvalho Chehab bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | 87bf6154dbSMauro Carvalho Chehab values: | reserved | vcpu_index | offset | 88bf6154dbSMauro Carvalho Chehab 89bf6154dbSMauro Carvalho Chehab All CPU interface regs are (rw, 32-bit) 90bf6154dbSMauro Carvalho Chehab 91bf6154dbSMauro Carvalho Chehab The offset specifies the offset from the "CPU interface base address" as 92bf6154dbSMauro Carvalho Chehab defined in the GICv2 specs. Getting or setting such a register has the 93bf6154dbSMauro Carvalho Chehab same effect as reading or writing the register on the actual hardware. 94bf6154dbSMauro Carvalho Chehab 95bf6154dbSMauro Carvalho Chehab The Active Priorities Registers APRn are implementation defined, so we set a 96bf6154dbSMauro Carvalho Chehab fixed format for our implementation that fits with the model of a "GICv2 97bf6154dbSMauro Carvalho Chehab implementation without the security extensions" which we present to the 98bf6154dbSMauro Carvalho Chehab guest. This interface always exposes four register APR[0-3] describing the 99bf6154dbSMauro Carvalho Chehab maximum possible 128 preemption levels. The semantics of the register 100bf6154dbSMauro Carvalho Chehab indicate if any interrupts in a given preemption level are in the active 101bf6154dbSMauro Carvalho Chehab state by setting the corresponding bit. 102bf6154dbSMauro Carvalho Chehab 103bf6154dbSMauro Carvalho Chehab Thus, preemption level X has one or more active interrupts if and only if: 104bf6154dbSMauro Carvalho Chehab 105bf6154dbSMauro Carvalho Chehab APRn[X mod 32] == 0b1, where n = X / 32 106bf6154dbSMauro Carvalho Chehab 107bf6154dbSMauro Carvalho Chehab Bits for undefined preemption levels are RAZ/WI. 108bf6154dbSMauro Carvalho Chehab 109bf6154dbSMauro Carvalho Chehab Note that this differs from a CPU's view of the APRs on hardware in which 110bf6154dbSMauro Carvalho Chehab a GIC without the security extensions expose group 0 and group 1 active 111bf6154dbSMauro Carvalho Chehab priorities in separate register groups, whereas we show a combined view 112bf6154dbSMauro Carvalho Chehab similar to GICv2's GICH_APR. 113bf6154dbSMauro Carvalho Chehab 114bf6154dbSMauro Carvalho Chehab For historical reasons and to provide ABI compatibility with userspace we 115bf6154dbSMauro Carvalho Chehab export the GICC_PMR register in the format of the GICH_VMCR.VMPriMask 116bf6154dbSMauro Carvalho Chehab field in the lower 5 bits of a word, meaning that userspace must always 117bf6154dbSMauro Carvalho Chehab use the lower 5 bits to communicate with the KVM device and must shift the 118bf6154dbSMauro Carvalho Chehab value left by 3 places to obtain the actual priority mask level. 119bf6154dbSMauro Carvalho Chehab 120bf6154dbSMauro Carvalho Chehab Errors: 121bf6154dbSMauro Carvalho Chehab 122bf6154dbSMauro Carvalho Chehab ======= ===================================================== 123bf6154dbSMauro Carvalho Chehab -ENXIO Getting or setting this register is not yet supported 124bf6154dbSMauro Carvalho Chehab -EBUSY One or more VCPUs are running 125bf6154dbSMauro Carvalho Chehab -EINVAL Invalid vcpu_index supplied 126bf6154dbSMauro Carvalho Chehab ======= ===================================================== 127bf6154dbSMauro Carvalho Chehab 128bf6154dbSMauro Carvalho Chehab KVM_DEV_ARM_VGIC_GRP_NR_IRQS 129bf6154dbSMauro Carvalho Chehab Attributes: 130bf6154dbSMauro Carvalho Chehab 131bf6154dbSMauro Carvalho Chehab A value describing the number of interrupts (SGI, PPI and SPI) for 132bf6154dbSMauro Carvalho Chehab this GIC instance, ranging from 64 to 1024, in increments of 32. 133bf6154dbSMauro Carvalho Chehab 134bf6154dbSMauro Carvalho Chehab Errors: 135bf6154dbSMauro Carvalho Chehab 136bf6154dbSMauro Carvalho Chehab ======= ============================================================= 137bf6154dbSMauro Carvalho Chehab -EINVAL Value set is out of the expected range 138bf6154dbSMauro Carvalho Chehab -EBUSY Value has already be set, or GIC has already been initialized 139bf6154dbSMauro Carvalho Chehab with default values. 140bf6154dbSMauro Carvalho Chehab ======= ============================================================= 141bf6154dbSMauro Carvalho Chehab 142bf6154dbSMauro Carvalho Chehab KVM_DEV_ARM_VGIC_GRP_CTRL 143bf6154dbSMauro Carvalho Chehab Attributes: 144bf6154dbSMauro Carvalho Chehab 145bf6154dbSMauro Carvalho Chehab KVM_DEV_ARM_VGIC_CTRL_INIT 146bf6154dbSMauro Carvalho Chehab request the initialization of the VGIC or ITS, no additional parameter 147bf6154dbSMauro Carvalho Chehab in kvm_device_attr.addr. 148bf6154dbSMauro Carvalho Chehab 149bf6154dbSMauro Carvalho Chehab Errors: 150bf6154dbSMauro Carvalho Chehab 151bf6154dbSMauro Carvalho Chehab ======= ========================================================= 152bf6154dbSMauro Carvalho Chehab -ENXIO VGIC not properly configured as required prior to calling 153bf6154dbSMauro Carvalho Chehab this attribute 154bf6154dbSMauro Carvalho Chehab -ENODEV no online VCPU 155bf6154dbSMauro Carvalho Chehab -ENOMEM memory shortage when allocating vgic internal data 156bf6154dbSMauro Carvalho Chehab ======= ========================================================= 157