| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
================================================== |
| 4 |
ARM Virtual Generic Interrupt Controller v2 (VGIC) |
| 5 |
================================================== |
| 6 |
|
| 7 |
Device types supported: |
| 8 |
|
| 9 |
- KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0 |
| 10 |
|
| 11 |
Only one VGIC instance may be instantiated through either this API or the |
| 12 |
legacy KVM_CREATE_IRQCHIP API. The created VGIC will act as the VM interrupt |
| 13 |
controller, requiring emulated user-space devices to inject interrupts to the |
| 14 |
VGIC instead of directly to CPUs. |
| 15 |
|
| 16 |
GICv3 implementations with hardware compatibility support allow creating a |
| 17 |
guest GICv2 through this interface. For information on creating a guest GICv3 |
| 18 |
device and guest ITS devices, see arm-vgic-v3.txt. It is not possible to |
| 19 |
create both a GICv3 and GICv2 device on the same VM. |
| 20 |
|
| 21 |
|
| 22 |
Groups: |
| 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 8 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 |
======= ========================================================= |