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