| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
=============================================== |
| 4 |
ARM Virtual Interrupt Translation Service (ITS) |
| 5 |
=============================================== |
| 6 |
|
| 7 |
Device types supported: |
| 8 |
KVM_DEV_TYPE_ARM_VGIC_ITS ARM Interrupt Translation Service Controller |
| 9 |
|
| 10 |
The ITS allows MSI(-X) interrupts to be injected into guests. This extension is |
| 11 |
optional. Creating a virtual ITS controller also requires a host GICv3 (see |
| 12 |
arm-vgic-v3.txt), but does not depend on having physical ITS controllers. |
| 13 |
|
| 14 |
There can be multiple ITS controllers per guest, each of them has to have |
| 15 |
a separate, non-overlapping MMIO region. |
| 16 |
|
| 17 |
|
| 18 |
Groups |
| 19 |
====== |
| 20 |
|
| 21 |
KVM_DEV_ARM_VGIC_GRP_ADDR |
| 22 |
------------------------- |
| 23 |
|
| 24 |
Attributes: |
| 25 |
KVM_VGIC_ITS_ADDR_TYPE (rw, 64-bit) |
| 26 |
Base address in the guest physical address space of the GICv3 ITS |
| 27 |
control register frame. |
| 28 |
This address needs to be 64K aligned and the region covers 128K. |
| 29 |
|
| 30 |
Errors: |
| 31 |
|
| 32 |
======= ================================================= |
| 33 |
-E2BIG Address outside of addressable IPA range |
| 34 |
-EINVAL Incorrectly aligned address |
| 35 |
-EEXIST Address already configured |
| 36 |
-EFAULT Invalid user pointer for attr->addr. |
| 37 |
-ENODEV Incorrect attribute or the ITS is not supported. |
| 38 |
======= ================================================= |
| 39 |
|
| 40 |
|
| 41 |
KVM_DEV_ARM_VGIC_GRP_CTRL |
| 42 |
------------------------- |
| 43 |
|
| 44 |
Attributes: |
| 45 |
KVM_DEV_ARM_VGIC_CTRL_INIT |
| 46 |
request the initialization of the ITS, no additional parameter in |
| 47 |
kvm_device_attr.addr. |
| 48 |
|
| 49 |
KVM_DEV_ARM_ITS_CTRL_RESET |
| 50 |
reset the ITS, no additional parameter in kvm_device_attr.addr. |
| 51 |
See "ITS Reset State" section. |
| 52 |
|
| 53 |
KVM_DEV_ARM_ITS_SAVE_TABLES |
| 54 |
save the ITS table data into guest RAM, at the location provisioned |
| 55 |
by the guest in corresponding registers/table entries. Should userspace |
| 56 |
require a form of dirty tracking to identify which pages are modified |
| 57 |
by the saving process, it should use a bitmap even if using another |
| 58 |
mechanism to track the memory dirtied by the vCPUs. |
| 59 |
|
| 60 |
The layout of the tables in guest memory defines an ABI. The entries |
| 61 |
are laid out in little endian format as described in the last paragraph. |
| 62 |
|
| 63 |
KVM_DEV_ARM_ITS_RESTORE_TABLES |
| 64 |
restore the ITS tables from guest RAM to ITS internal structures. |
| 65 |
|
| 66 |
The GICV3 must be restored before the ITS and all ITS registers but |
| 67 |
the GITS_CTLR must be restored before restoring the ITS tables. |
| 68 |
|
| 69 |
The GITS_IIDR read-only register must also be restored before |
| 70 |
calling KVM_DEV_ARM_ITS_RESTORE_TABLES as the IIDR revision field |
| 71 |
encodes the ABI revision. |
| 72 |
|
| 73 |
The expected ordering when restoring the GICv3/ITS is described in section |
| 74 |
"ITS Restore Sequence". |
| 75 |
|
| 76 |
Errors: |
| 77 |
|
| 78 |
======= ========================================================== |
| 79 |
-ENXIO ITS not properly configured as required prior to setting |
| 80 |
this attribute |
| 81 |
-ENOMEM Memory shortage when allocating ITS internal data |
| 82 |
-EINVAL Inconsistent restored data |
| 83 |
-EFAULT Invalid guest ram access |
| 84 |
-EBUSY One or more VCPUS are running |
| 85 |
-EACCES The virtual ITS is backed by a physical GICv4 ITS, and the |
| 86 |
state is not available without GICv4.1 |
| 87 |
======= ========================================================== |
| 88 |
|
| 89 |
KVM_DEV_ARM_VGIC_GRP_ITS_REGS |
| 90 |
----------------------------- |
| 91 |
|
| 92 |
Attributes: |
| 93 |
The attr field of kvm_device_attr encodes the offset of the |
| 94 |
ITS register, relative to the ITS control frame base address |
| 95 |
(ITS_base). |
| 96 |
|
| 97 |
kvm_device_attr.addr points to a __u64 value whatever the width |
| 98 |
of the addressed register (32/64 bits). 64 bit registers can only |
| 99 |
be accessed with full length. |
| 100 |
|
| 101 |
Writes to read-only registers are ignored by the kernel except for: |
| 102 |
|
| 103 |
- GITS_CREADR. It must be restored otherwise commands in the queue |
| 104 |
will be re-executed after restoring CWRITER. GITS_CREADR must be |
| 105 |
restored before restoring the GITS_CTLR which is likely to enable the |
| 106 |
ITS. Also it must be restored after GITS_CBASER since a write to |
| 107 |
GITS_CBASER resets GITS_CREADR. |
| 108 |
- GITS_IIDR. The Revision field encodes the table layout ABI revision. |
| 109 |
In the future we might implement direct injection of virtual LPIs. |
| 110 |
This will require an upgrade of the table layout and an evolution of |
| 111 |
the ABI. GITS_IIDR must be restored before calling |
| 112 |
KVM_DEV_ARM_ITS_RESTORE_TABLES. |
| 113 |
|
| 114 |
For other registers, getting or setting a register has the same |
| 115 |
effect as reading/writing the register on real hardware. |
| 116 |
|
| 117 |
Errors: |
| 118 |
|
| 119 |
======= ==================================================== |
| 120 |
-ENXIO Offset does not correspond to any supported register |
| 121 |
-EFAULT Invalid user pointer for attr->addr |
| 122 |
-EINVAL Offset is not 64-bit aligned |
| 123 |
-EBUSY one or more VCPUS are running |
| 124 |
======= ==================================================== |
| 125 |
|
| 126 |
ITS Restore Sequence: |
| 127 |
--------------------- |
| 128 |
|
| 129 |
The following ordering must be followed when restoring the GIC, ITS, and |
| 130 |
KVM_IRQFD assignments: |
| 131 |
|
| 132 |
a) restore all guest memory and create vcpus |
| 133 |
b) restore all redistributors |
| 134 |
c) provide the ITS base address |
| 135 |
(KVM_DEV_ARM_VGIC_GRP_ADDR) |
| 136 |
d) restore the ITS in the following order: |
| 137 |
|
| 138 |
1. Restore GITS_CBASER |
| 139 |
2. Restore all other ``GITS_`` registers, except GITS_CTLR! |
| 140 |
3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES) |
| 141 |
4. Restore GITS_CTLR |
| 142 |
|
| 143 |
e) restore KVM_IRQFD assignments for MSIs |
| 144 |
|
| 145 |
Then vcpus can be started. |
| 146 |
|
| 147 |
ITS Table ABI REV0: |
| 148 |
------------------- |
| 149 |
|
| 150 |
Revision 0 of the ABI only supports the features of a virtual GICv3, and does |
| 151 |
not support a virtual GICv4 with support for direct injection of virtual |
| 152 |
interrupts for nested hypervisors. |
| 153 |
|
| 154 |
The device table and ITT are indexed by the DeviceID and EventID, |
| 155 |
respectively. The collection table is not indexed by CollectionID, and the |
| 156 |
entries in the collection are listed in no particular order. |
| 157 |
All entries are 8 bytes. |
| 158 |
|
| 159 |
Device Table Entry (DTE):: |
| 160 |
|
| 161 |
bits: | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 | |
| 162 |
values: | V | next | ITT_addr | Size | |
| 163 |
|
| 164 |
where: |
| 165 |
|
| 166 |
- V indicates whether the entry is valid. If not, other fields |
| 167 |
are not meaningful. |
| 168 |
- next: equals to 0 if this entry is the last one; otherwise it |
| 169 |
corresponds to the DeviceID offset to the next DTE, capped by |
| 170 |
2^14 -1. |
| 171 |
- ITT_addr matches bits [51:8] of the ITT address (256 Byte aligned). |
| 172 |
- Size specifies the supported number of bits for the EventID, |
| 173 |
minus one |
| 174 |
|
| 175 |
Collection Table Entry (CTE):: |
| 176 |
|
| 177 |
bits: | 63| 62 .. 52 | 51 ... 16 | 15 ... 0 | |
| 178 |
values: | V | RES0 | RDBase | ICID | |
| 179 |
|
| 180 |
where: |
| 181 |
|
| 182 |
- V indicates whether the entry is valid. If not, other fields are |
| 183 |
not meaningful. |
| 184 |
- RES0: reserved field with Should-Be-Zero-or-Preserved behavior. |
| 185 |
- RDBase is the PE number (GICR_TYPER.Processor_Number semantic), |
| 186 |
- ICID is the collection ID |
| 187 |
|
| 188 |
Interrupt Translation Entry (ITE):: |
| 189 |
|
| 190 |
bits: | 63 ... 48 | 47 ... 16 | 15 ... 0 | |
| 191 |
values: | next | pINTID | ICID | |
| 192 |
|
| 193 |
where: |
| 194 |
|
| 195 |
- next: equals to 0 if this entry is the last one; otherwise it corresponds |
| 196 |
to the EventID offset to the next ITE capped by 2^16 -1. |
| 197 |
- pINTID is the physical LPI ID; if zero, it means the entry is not valid |
| 198 |
and other fields are not meaningful. |
| 199 |
- ICID is the collection ID |
| 200 |
|
| 201 |
ITS Reset State: |
| 202 |
---------------- |
| 203 |
|
| 204 |
RESET returns the ITS to the same state that it was when first created and |
| 205 |
initialized. When the RESET command returns, the following things are |
| 206 |
guaranteed: |
| 207 |
|
| 208 |
- The ITS is not enabled and quiescent |
| 209 |
GITS_CTLR.Enabled = 0 .Quiescent=1 |
| 210 |
- There is no internally cached state |
| 211 |
- No collection or device table are used |
| 212 |
GITS_BASER<n>.Valid = 0 |
| 213 |
- GITS_CBASER = 0, GITS_CREADR = 0, GITS_CWRITER = 0 |
| 214 |
- The ABI version is unchanged and remains the one set when the ITS |
| 215 |
device was first created. |