157 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 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.010 11Only one VGIC instance may be instantiated through either this API or the12legacy KVM_CREATE_IRQCHIP API. The created VGIC will act as the VM interrupt13controller, requiring emulated user-space devices to inject interrupts to the14VGIC instead of directly to CPUs.15 16GICv3 implementations with hardware compatibility support allow creating a17guest GICv2 through this interface. For information on creating a guest GICv318device and guest ITS devices, see arm-vgic-v3.txt. It is not possible to19create both a GICv3 and GICv2 device on the same VM.20 21 22Groups:23 KVM_DEV_ARM_VGIC_GRP_ADDR24 Attributes:25 26 KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit)27 Base address in the guest physical address space of the GIC distributor28 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 cpu33 interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.34 This address needs to be 4K aligned and the region covers 8 KByte.35 36 Errors:37 38 ======= =============================================================39 -E2BIG Address outside of addressable IPA range40 -EINVAL Incorrectly aligned address41 -EEXIST Address already configured42 -ENXIO The group or attribute is unknown/unsupported for this device43 or hardware support is missing.44 -EFAULT Invalid user pointer for attr->addr.45 ======= =============================================================46 47 KVM_DEV_ARM_VGIC_GRP_DIST_REGS48 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 the58 GICv2 specs. Getting or setting such a register has the same effect as59 reading or writing the register on the actual hardware from the cpu whose60 index is specified with the vcpu_index field. Note that most distributor61 fields are not banked, but return the same value regardless of the62 vcpu_index used to access the register.63 64 GICD_IIDR.Revision is updated when the KVM implementation of an emulated65 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 to67 confirm its expected behavior is aligned with the KVM implementation.68 Userspace should set GICD_IIDR before setting any other registers (both69 KVM_DEV_ARM_VGIC_GRP_DIST_REGS and KVM_DEV_ARM_VGIC_GRP_CPU_REGS) to ensure70 the expected behavior. Unless GICD_IIDR has been set from userspace, writes71 to the interrupt group registers (GICD_IGROUPR) are ignored.72 73 Errors:74 75 ======= =====================================================76 -ENXIO Getting or setting this register is not yet supported77 -EBUSY One or more VCPUs are running78 -EINVAL Invalid vcpu_index supplied79 ======= =====================================================80 81 KVM_DEV_ARM_VGIC_GRP_CPU_REGS82 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" as92 defined in the GICv2 specs. Getting or setting such a register has the93 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 a96 fixed format for our implementation that fits with the model of a "GICv297 implementation without the security extensions" which we present to the98 guest. This interface always exposes four register APR[0-3] describing the99 maximum possible 128 preemption levels. The semantics of the register100 indicate if any interrupts in a given preemption level are in the active101 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 / 32106 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 which110 a GIC without the security extensions expose group 0 and group 1 active111 priorities in separate register groups, whereas we show a combined view112 similar to GICv2's GICH_APR.113 114 For historical reasons and to provide ABI compatibility with userspace we115 export the GICC_PMR register in the format of the GICH_VMCR.VMPriMask116 field in the lower 5 bits of a word, meaning that userspace must always117 use the lower 5 bits to communicate with the KVM device and must shift the118 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 supported124 -EBUSY One or more VCPUs are running125 -EINVAL Invalid vcpu_index supplied126 ======= =====================================================127 128 KVM_DEV_ARM_VGIC_GRP_NR_IRQS129 Attributes:130 131 A value describing the number of interrupts (SGI, PPI and SPI) for132 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 range138 -EBUSY Value has already be set, or GIC has already been initialized139 with default values.140 ======= =============================================================141 142 KVM_DEV_ARM_VGIC_GRP_CTRL143 Attributes:144 145 KVM_DEV_ARM_VGIC_CTRL_INIT146 request the initialization of the VGIC or ITS, no additional parameter147 in kvm_device_attr.addr.148 149 Errors:150 151 ======= =========================================================152 -ENXIO VGIC not properly configured as required prior to calling153 this attribute154 -ENODEV no online VCPU155 -ENOMEM memory shortage when allocating vgic internal data156 ======= =========================================================157