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