0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==============================================================
0004 ARM Virtual Generic Interrupt Controller v3 and later (VGICv3)
0005 ==============================================================
0006
0007
0008 Device types supported:
0009 - KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0
0010
0011 Only one VGIC instance may be instantiated through this API. The created VGIC
0012 will act as the VM interrupt controller, requiring emulated user-space devices
0013 to inject interrupts to the VGIC instead of directly to CPUs. It is not
0014 possible to create both a GICv3 and GICv2 on the same VM.
0015
0016 Creating a guest GICv3 device requires a host GICv3 as well.
0017
0018
0019 Groups:
0020 KVM_DEV_ARM_VGIC_GRP_ADDR
0021 Attributes:
0022
0023 KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit)
0024 Base address in the guest physical address space of the GICv3 distributor
0025 register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
0026 This address needs to be 64K aligned and the region covers 64 KByte.
0027
0028 KVM_VGIC_V3_ADDR_TYPE_REDIST (rw, 64-bit)
0029 Base address in the guest physical address space of the GICv3
0030 redistributor register mappings. There are two 64K pages for each
0031 VCPU and all of the redistributor pages are contiguous.
0032 Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
0033 This address needs to be 64K aligned.
0034
0035 KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION (rw, 64-bit)
0036 The attribute data pointed to by kvm_device_attr.addr is a __u64 value::
0037
0038 bits: | 63 .... 52 | 51 .... 16 | 15 - 12 |11 - 0
0039 values: | count | base | flags | index
0040
0041 - index encodes the unique redistributor region index
0042 - flags: reserved for future use, currently 0
0043 - base field encodes bits [51:16] of the guest physical base address
0044 of the first redistributor in the region.
0045 - count encodes the number of redistributors in the region. Must be
0046 greater than 0.
0047
0048 There are two 64K pages for each redistributor in the region and
0049 redistributors are laid out contiguously within the region. Regions
0050 are filled with redistributors in the index order. The sum of all
0051 region count fields must be greater than or equal to the number of
0052 VCPUs. Redistributor regions must be registered in the incremental
0053 index order, starting from index 0.
0054
0055 The characteristics of a specific redistributor region can be read
0056 by presetting the index field in the attr data.
0057 Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
0058
0059 It is invalid to mix calls with KVM_VGIC_V3_ADDR_TYPE_REDIST and
0060 KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes.
0061
0062 Errors:
0063
0064 ======= =============================================================
0065 -E2BIG Address outside of addressable IPA range
0066 -EINVAL Incorrectly aligned address, bad redistributor region
0067 count/index, mixed redistributor region attribute usage
0068 -EEXIST Address already configured
0069 -ENOENT Attempt to read the characteristics of a non existing
0070 redistributor region
0071 -ENXIO The group or attribute is unknown/unsupported for this device
0072 or hardware support is missing.
0073 -EFAULT Invalid user pointer for attr->addr.
0074 ======= =============================================================
0075
0076
0077 KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS
0078 Attributes:
0079
0080 The attr field of kvm_device_attr encodes two values::
0081
0082 bits: | 63 .... 32 | 31 .... 0 |
0083 values: | mpidr | offset |
0084
0085 All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a
0086 __u32 value. 64-bit registers must be accessed by separately accessing the
0087 lower and higher word.
0088
0089 Writes to read-only registers are ignored by the kernel.
0090
0091 KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers.
0092 KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU
0093 specified by the mpidr.
0094
0095 The offset is relative to the "[Re]Distributor base address" as defined
0096 in the GICv3/4 specs. Getting or setting such a register has the same
0097 effect as reading or writing the register on real hardware, except for the
0098 following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR,
0099 GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0. These registers behave
0100 differently when accessed via this interface compared to their
0101 architecturally defined behavior to allow software a full view of the
0102 VGIC's internal state.
0103
0104 The mpidr field is used to specify which
0105 redistributor is accessed. The mpidr is ignored for the distributor.
0106
0107 The mpidr encoding is based on the affinity information in the
0108 architecture defined MPIDR, and the field is encoded as follows::
0109
0110 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
0111 | Aff3 | Aff2 | Aff1 | Aff0 |
0112
0113 Note that distributor fields are not banked, but return the same value
0114 regardless of the mpidr used to access the register.
0115
0116 GICD_IIDR.Revision is updated when the KVM implementation is changed in a
0117 way directly observable by the guest or userspace. Userspace should read
0118 GICD_IIDR from KVM and write back the read value to confirm its expected
0119 behavior is aligned with the KVM implementation. Userspace should set
0120 GICD_IIDR before setting any other registers to ensure the expected
0121 behavior.
0122
0123
0124 The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such
0125 that a write of a clear bit has no effect, whereas a write with a set bit
0126 clears that value. To allow userspace to freely set the values of these two
0127 registers, setting the attributes with the register offsets for these two
0128 registers simply sets the non-reserved bits to the value written.
0129
0130
0131 Accesses (reads and writes) to the GICD_ISPENDR register region and
0132 GICR_ISPENDR0 registers get/set the value of the latched pending state for
0133 the interrupts.
0134
0135 This is identical to the value returned by a guest read from ISPENDR for an
0136 edge triggered interrupt, but may differ for level triggered interrupts.
0137 For edge triggered interrupts, once an interrupt becomes pending (whether
0138 because of an edge detected on the input line or because of a guest write
0139 to ISPENDR) this state is "latched", and only cleared when either the
0140 interrupt is activated or when the guest writes to ICPENDR. A level
0141 triggered interrupt may be pending either because the level input is held
0142 high by a device, or because of a guest write to the ISPENDR register. Only
0143 ISPENDR writes are latched; if the device lowers the line level then the
0144 interrupt is no longer pending unless the guest also wrote to ISPENDR, and
0145 conversely writes to ICPENDR or activations of the interrupt do not clear
0146 the pending status if the line level is still being held high. (These
0147 rules are documented in the GICv3 specification descriptions of the ICPENDR
0148 and ISPENDR registers.) For a level triggered interrupt the value accessed
0149 here is that of the latch which is set by ISPENDR and cleared by ICPENDR or
0150 interrupt activation, whereas the value returned by a guest read from
0151 ISPENDR is the logical OR of the latch value and the input line level.
0152
0153 Raw access to the latch state is provided to userspace so that it can save
0154 and restore the entire GIC internal state (which is defined by the
0155 combination of the current input line level and the latch state, and cannot
0156 be deduced from purely the line level and the value of the ISPENDR
0157 registers).
0158
0159 Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have
0160 RAZ/WI semantics, meaning that reads always return 0 and writes are always
0161 ignored.
0162
0163 Errors:
0164
0165 ====== =====================================================
0166 -ENXIO Getting or setting this register is not yet supported
0167 -EBUSY One or more VCPUs are running
0168 ====== =====================================================
0169
0170
0171 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS
0172 Attributes:
0173
0174 The attr field of kvm_device_attr encodes two values::
0175
0176 bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 |
0177 values: | mpidr | RES | instr |
0178
0179 The mpidr field encodes the CPU ID based on the affinity information in the
0180 architecture defined MPIDR, and the field is encoded as follows::
0181
0182 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
0183 | Aff3 | Aff2 | Aff1 | Aff0 |
0184
0185 The instr field encodes the system register to access based on the fields
0186 defined in the A64 instruction set encoding for system register access
0187 (RES means the bits are reserved for future use and should be zero)::
0188
0189 | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 |
0190 | Op 0 | Op1 | CRn | CRm | Op2 |
0191
0192 All system regs accessed through this API are (rw, 64-bit) and
0193 kvm_device_attr.addr points to a __u64 value.
0194
0195 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the
0196 CPU specified by the mpidr field.
0197
0198 CPU interface registers access is not implemented for AArch32 mode.
0199 Error -ENXIO is returned when accessed in AArch32 mode.
0200
0201 Errors:
0202
0203 ======= =====================================================
0204 -ENXIO Getting or setting this register is not yet supported
0205 -EBUSY VCPU is running
0206 -EINVAL Invalid mpidr or register value supplied
0207 ======= =====================================================
0208
0209
0210 KVM_DEV_ARM_VGIC_GRP_NR_IRQS
0211 Attributes:
0212
0213 A value describing the number of interrupts (SGI, PPI and SPI) for
0214 this GIC instance, ranging from 64 to 1024, in increments of 32.
0215
0216 kvm_device_attr.addr points to a __u32 value.
0217
0218 Errors:
0219
0220 ======= ======================================
0221 -EINVAL Value set is out of the expected range
0222 -EBUSY Value has already be set.
0223 ======= ======================================
0224
0225
0226 KVM_DEV_ARM_VGIC_GRP_CTRL
0227 Attributes:
0228
0229 KVM_DEV_ARM_VGIC_CTRL_INIT
0230 request the initialization of the VGIC, no additional parameter in
0231 kvm_device_attr.addr. Must be called after all VCPUs have been created.
0232 KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES
0233 save all LPI pending bits into guest RAM pending tables.
0234
0235 The first kB of the pending table is not altered by this operation.
0236
0237 Errors:
0238
0239 ======= ========================================================
0240 -ENXIO VGIC not properly configured as required prior to calling
0241 this attribute
0242 -ENODEV no online VCPU
0243 -ENOMEM memory shortage when allocating vgic internal data
0244 -EFAULT Invalid guest ram access
0245 -EBUSY One or more VCPUS are running
0246 ======= ========================================================
0247
0248
0249 KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO
0250 Attributes:
0251
0252 The attr field of kvm_device_attr encodes the following values::
0253
0254 bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 |
0255 values: | mpidr | info | vINTID |
0256
0257 The vINTID specifies which set of IRQs is reported on.
0258
0259 The info field specifies which information userspace wants to get or set
0260 using this interface. Currently we support the following info values:
0261
0262 VGIC_LEVEL_INFO_LINE_LEVEL:
0263 Get/Set the input level of the IRQ line for a set of 32 contiguously
0264 numbered interrupts.
0265
0266 vINTID must be a multiple of 32.
0267
0268 kvm_device_attr.addr points to a __u32 value which will contain a
0269 bitmap where a set bit means the interrupt level is asserted.
0270
0271 Bit[n] indicates the status for interrupt vINTID + n.
0272
0273 SGIs and any interrupt with a higher ID than the number of interrupts
0274 supported, will be RAZ/WI. LPIs are always edge-triggered and are
0275 therefore not supported by this interface.
0276
0277 PPIs are reported per VCPU as specified in the mpidr field, and SPIs are
0278 reported with the same value regardless of the mpidr specified.
0279
0280 The mpidr field encodes the CPU ID based on the affinity information in the
0281 architecture defined MPIDR, and the field is encoded as follows::
0282
0283 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
0284 | Aff3 | Aff2 | Aff1 | Aff0 |
0285
0286 Errors:
0287
0288 ======= =============================================
0289 -EINVAL vINTID is not multiple of 32 or info field is
0290 not VGIC_LEVEL_INFO_LINE_LEVEL
0291 ======= =============================================
