1 .. SPDX-License-Identifier: GPL-2.0
3 ===============================================
4 ARM Virtual Interrupt Translation Service (ITS)
5 ===============================================
7 Device types supported:
8 KVM_DEV_TYPE_ARM_VGIC_ITS ARM Interrupt Translation Service Controller
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.
14 There can be multiple ITS controllers per guest, each of them has to have
15 a separate, non-overlapping MMIO region.
21 KVM_DEV_ARM_VGIC_GRP_ADDR
22 -------------------------
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.
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 ======= =================================================
41 KVM_DEV_ARM_VGIC_GRP_CTRL
42 -------------------------
45 KVM_DEV_ARM_VGIC_CTRL_INIT
46 request the initialization of the ITS, no additional parameter in
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.
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.
57 The layout of the tables in guest memory defines an ABI. The entries
58 are laid out in little endian format as described in the last paragraph.
60 KVM_DEV_ARM_ITS_RESTORE_TABLES
61 restore the ITS tables from guest RAM to ITS internal structures.
63 The GICV3 must be restored before the ITS and all ITS registers but
64 the GITS_CTLR must be restored before restoring the ITS tables.
66 The GITS_IIDR read-only register must also be restored before
67 calling KVM_DEV_ARM_ITS_RESTORE_TABLES as the IIDR revision field
68 encodes the ABI revision.
70 The expected ordering when restoring the GICv3/ITS is described in section
71 "ITS Restore Sequence".
75 ======= ==========================================================
76 -ENXIO ITS not properly configured as required prior to setting
78 -ENOMEM Memory shortage when allocating ITS internal data
79 -EINVAL Inconsistent restored data
80 -EFAULT Invalid guest ram access
81 -EBUSY One or more VCPUS are running
82 -EACCES The virtual ITS is backed by a physical GICv4 ITS, and the
83 state is not available
84 ======= ==========================================================
86 KVM_DEV_ARM_VGIC_GRP_ITS_REGS
87 -----------------------------
90 The attr field of kvm_device_attr encodes the offset of the
91 ITS register, relative to the ITS control frame base address
94 kvm_device_attr.addr points to a __u64 value whatever the width
95 of the addressed register (32/64 bits). 64 bit registers can only
96 be accessed with full length.
98 Writes to read-only registers are ignored by the kernel except for:
100 - GITS_CREADR. It must be restored otherwise commands in the queue
101 will be re-executed after restoring CWRITER. GITS_CREADR must be
102 restored before restoring the GITS_CTLR which is likely to enable the
103 ITS. Also it must be restored after GITS_CBASER since a write to
104 GITS_CBASER resets GITS_CREADR.
105 - GITS_IIDR. The Revision field encodes the table layout ABI revision.
106 In the future we might implement direct injection of virtual LPIs.
107 This will require an upgrade of the table layout and an evolution of
108 the ABI. GITS_IIDR must be restored before calling
109 KVM_DEV_ARM_ITS_RESTORE_TABLES.
111 For other registers, getting or setting a register has the same
112 effect as reading/writing the register on real hardware.
116 ======= ====================================================
117 -ENXIO Offset does not correspond to any supported register
118 -EFAULT Invalid user pointer for attr->addr
119 -EINVAL Offset is not 64-bit aligned
120 -EBUSY one or more VCPUS are running
121 ======= ====================================================
123 ITS Restore Sequence:
124 ---------------------
126 The following ordering must be followed when restoring the GIC and the ITS:
128 a) restore all guest memory and create vcpus
129 b) restore all redistributors
130 c) provide the ITS base address
131 (KVM_DEV_ARM_VGIC_GRP_ADDR)
132 d) restore the ITS in the following order:
134 1. Restore GITS_CBASER
135 2. Restore all other ``GITS_`` registers, except GITS_CTLR!
136 3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES)
139 Then vcpus can be started.
144 Revision 0 of the ABI only supports the features of a virtual GICv3, and does
145 not support a virtual GICv4 with support for direct injection of virtual
146 interrupts for nested hypervisors.
148 The device table and ITT are indexed by the DeviceID and EventID,
149 respectively. The collection table is not indexed by CollectionID, and the
150 entries in the collection are listed in no particular order.
151 All entries are 8 bytes.
153 Device Table Entry (DTE)::
155 bits: | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 |
156 values: | V | next | ITT_addr | Size |
160 - V indicates whether the entry is valid. If not, other fields
162 - next: equals to 0 if this entry is the last one; otherwise it
163 corresponds to the DeviceID offset to the next DTE, capped by
165 - ITT_addr matches bits [51:8] of the ITT address (256 Byte aligned).
166 - Size specifies the supported number of bits for the EventID,
169 Collection Table Entry (CTE)::
171 bits: | 63| 62 .. 52 | 51 ... 16 | 15 ... 0 |
172 values: | V | RES0 | RDBase | ICID |
176 - V indicates whether the entry is valid. If not, other fields are
178 - RES0: reserved field with Should-Be-Zero-or-Preserved behavior.
179 - RDBase is the PE number (GICR_TYPER.Processor_Number semantic),
180 - ICID is the collection ID
182 Interrupt Translation Entry (ITE)::
184 bits: | 63 ... 48 | 47 ... 16 | 15 ... 0 |
185 values: | next | pINTID | ICID |
189 - next: equals to 0 if this entry is the last one; otherwise it corresponds
190 to the EventID offset to the next ITE capped by 2^16 -1.
191 - pINTID is the physical LPI ID; if zero, it means the entry is not valid
192 and other fields are not meaningful.
193 - ICID is the collection ID
198 RESET returns the ITS to the same state that it was when first created and
199 initialized. When the RESET command returns, the following things are
202 - The ITS is not enabled and quiescent
203 GITS_CTLR.Enabled = 0 .Quiescent=1
204 - There is no internally cached state
205 - No collection or device table are used
206 GITS_BASER<n>.Valid = 0
207 - GITS_CBASER = 0, GITS_CREADR = 0, GITS_CWRITER = 0
208 - The ABI version is unchanged and remains the one set when the ITS
209 device was first created.