0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==================================================
0004 ARM Virtual Generic Interrupt Controller v2 (VGIC)
0005 ==================================================
0006
0007 Device types supported:
0008
0009 - KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0
0010
0011 Only one VGIC instance may be instantiated through either this API or the
0012 legacy KVM_CREATE_IRQCHIP API. The created VGIC will act as the VM interrupt
0013 controller, requiring emulated user-space devices to inject interrupts to the
0014 VGIC instead of directly to CPUs.
0015
0016 GICv3 implementations with hardware compatibility support allow creating a
0017 guest GICv2 through this interface. For information on creating a guest GICv3
0018 device and guest ITS devices, see arm-vgic-v3.txt. It is not possible to
0019 create both a GICv3 and GICv2 device on the same VM.
0020
0021
0022 Groups:
0023 KVM_DEV_ARM_VGIC_GRP_ADDR
0024 Attributes:
0025
0026 KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit)
0027 Base address in the guest physical address space of the GIC distributor
0028 register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
0029 This address needs to be 4K aligned and the region covers 4 KByte.
0030
0031 KVM_VGIC_V2_ADDR_TYPE_CPU (rw, 64-bit)
0032 Base address in the guest physical address space of the GIC virtual cpu
0033 interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
0034 This address needs to be 4K aligned and the region covers 4 KByte.
0035
0036 Errors:
0037
0038 ======= =============================================================
0039 -E2BIG Address outside of addressable IPA range
0040 -EINVAL Incorrectly aligned address
0041 -EEXIST Address already configured
0042 -ENXIO The group or attribute is unknown/unsupported for this device
0043 or hardware support is missing.
0044 -EFAULT Invalid user pointer for attr->addr.
0045 ======= =============================================================
0046
0047 KVM_DEV_ARM_VGIC_GRP_DIST_REGS
0048 Attributes:
0049
0050 The attr field of kvm_device_attr encodes two values::
0051
0052 bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 |
0053 values: | reserved | vcpu_index | offset |
0054
0055 All distributor regs are (rw, 32-bit)
0056
0057 The offset is relative to the "Distributor base address" as defined in the
0058 GICv2 specs. Getting or setting such a register has the same effect as
0059 reading or writing the register on the actual hardware from the cpu whose
0060 index is specified with the vcpu_index field. Note that most distributor
0061 fields are not banked, but return the same value regardless of the
0062 vcpu_index used to access the register.
0063
0064 GICD_IIDR.Revision is updated when the KVM implementation of an emulated
0065 GICv2 is changed in a way directly observable by the guest or userspace.
0066 Userspace should read GICD_IIDR from KVM and write back the read value to
0067 confirm its expected behavior is aligned with the KVM implementation.
0068 Userspace should set GICD_IIDR before setting any other registers (both
0069 KVM_DEV_ARM_VGIC_GRP_DIST_REGS and KVM_DEV_ARM_VGIC_GRP_CPU_REGS) to ensure
0070 the expected behavior. Unless GICD_IIDR has been set from userspace, writes
0071 to the interrupt group registers (GICD_IGROUPR) are ignored.
0072
0073 Errors:
0074
0075 ======= =====================================================
0076 -ENXIO Getting or setting this register is not yet supported
0077 -EBUSY One or more VCPUs are running
0078 -EINVAL Invalid vcpu_index supplied
0079 ======= =====================================================
0080
0081 KVM_DEV_ARM_VGIC_GRP_CPU_REGS
0082 Attributes:
0083
0084 The attr field of kvm_device_attr encodes two values::
0085
0086 bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 |
0087 values: | reserved | vcpu_index | offset |
0088
0089 All CPU interface regs are (rw, 32-bit)
0090
0091 The offset specifies the offset from the "CPU interface base address" as
0092 defined in the GICv2 specs. Getting or setting such a register has the
0093 same effect as reading or writing the register on the actual hardware.
0094
0095 The Active Priorities Registers APRn are implementation defined, so we set a
0096 fixed format for our implementation that fits with the model of a "GICv2
0097 implementation without the security extensions" which we present to the
0098 guest. This interface always exposes four register APR[0-3] describing the
0099 maximum possible 128 preemption levels. The semantics of the register
0100 indicate if any interrupts in a given preemption level are in the active
0101 state by setting the corresponding bit.
0102
0103 Thus, preemption level X has one or more active interrupts if and only if:
0104
0105 APRn[X mod 32] == 0b1, where n = X / 32
0106
0107 Bits for undefined preemption levels are RAZ/WI.
0108
0109 Note that this differs from a CPU's view of the APRs on hardware in which
0110 a GIC without the security extensions expose group 0 and group 1 active
0111 priorities in separate register groups, whereas we show a combined view
0112 similar to GICv2's GICH_APR.
0113
0114 For historical reasons and to provide ABI compatibility with userspace we
0115 export the GICC_PMR register in the format of the GICH_VMCR.VMPriMask
0116 field in the lower 5 bits of a word, meaning that userspace must always
0117 use the lower 5 bits to communicate with the KVM device and must shift the
0118 value left by 3 places to obtain the actual priority mask level.
0119
0120 Errors:
0121
0122 ======= =====================================================
0123 -ENXIO Getting or setting this register is not yet supported
0124 -EBUSY One or more VCPUs are running
0125 -EINVAL Invalid vcpu_index supplied
0126 ======= =====================================================
0127
0128 KVM_DEV_ARM_VGIC_GRP_NR_IRQS
0129 Attributes:
0130
0131 A value describing the number of interrupts (SGI, PPI and SPI) for
0132 this GIC instance, ranging from 64 to 1024, in increments of 32.
0133
0134 Errors:
0135
0136 ======= =============================================================
0137 -EINVAL Value set is out of the expected range
0138 -EBUSY Value has already be set, or GIC has already been initialized
0139 with default values.
0140 ======= =============================================================
0141
0142 KVM_DEV_ARM_VGIC_GRP_CTRL
0143 Attributes:
0144
0145 KVM_DEV_ARM_VGIC_CTRL_INIT
0146 request the initialization of the VGIC or ITS, no additional parameter
0147 in kvm_device_attr.addr.
0148
0149 Errors:
0150
0151 ======= =========================================================
0152 -ENXIO VGIC not properly configured as required prior to calling
0153 this attribute
0154 -ENODEV no online VCPU
0155 -ENOMEM memory shortage when allocating vgic internal data
0156 ======= =========================================================
