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