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