1.. SPDX-License-Identifier: GPL-2.0 2 3=============================================== 4ARM Virtual Interrupt Translation Service (ITS) 5=============================================== 6 7Device types supported: 8 KVM_DEV_TYPE_ARM_VGIC_ITS ARM Interrupt Translation Service Controller 9 10The ITS allows MSI(-X) interrupts to be injected into guests. This extension is 11optional. Creating a virtual ITS controller also requires a host GICv3 (see 12arm-vgic-v3.txt), but does not depend on having physical ITS controllers. 13 14There can be multiple ITS controllers per guest, each of them has to have 15a separate, non-overlapping MMIO region. 16 17 18Groups 19====== 20 21KVM_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 41KVM_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 89KVM_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 126ITS Restore Sequence: 127--------------------- 128 129The following ordering must be followed when restoring the GIC, ITS, and 130KVM_IRQFD assignments: 131 132a) restore all guest memory and create vcpus 133b) restore all redistributors 134c) provide the ITS base address 135 (KVM_DEV_ARM_VGIC_GRP_ADDR) 136d) 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 143e) restore KVM_IRQFD assignments for MSIs 144 145Then vcpus can be started. 146 147ITS 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 201ITS Reset State: 202---------------- 203 204RESET returns the ITS to the same state that it was when first created and 205initialized. When the RESET command returns, the following things are 206guaranteed: 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. 216