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