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 and the ITS:
130
131a) restore all guest memory and create vcpus
132b) restore all redistributors
133c) provide the ITS base address
134   (KVM_DEV_ARM_VGIC_GRP_ADDR)
135d) restore the ITS in the following order:
136
137     1. Restore GITS_CBASER
138     2. Restore all other ``GITS_`` registers, except GITS_CTLR!
139     3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES)
140     4. Restore GITS_CTLR
141
142Then vcpus can be started.
143
144ITS Table ABI REV0:
145-------------------
146
147 Revision 0 of the ABI only supports the features of a virtual GICv3, and does
148 not support a virtual GICv4 with support for direct injection of virtual
149 interrupts for nested hypervisors.
150
151 The device table and ITT are indexed by the DeviceID and EventID,
152 respectively. The collection table is not indexed by CollectionID, and the
153 entries in the collection are listed in no particular order.
154 All entries are 8 bytes.
155
156 Device Table Entry (DTE)::
157
158   bits:     | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 |
159   values:   | V |   next    | ITT_addr |  Size   |
160
161 where:
162
163 - V indicates whether the entry is valid. If not, other fields
164   are not meaningful.
165 - next: equals to 0 if this entry is the last one; otherwise it
166   corresponds to the DeviceID offset to the next DTE, capped by
167   2^14 -1.
168 - ITT_addr matches bits [51:8] of the ITT address (256 Byte aligned).
169 - Size specifies the supported number of bits for the EventID,
170   minus one
171
172 Collection Table Entry (CTE)::
173
174   bits:     | 63| 62 ..  52  | 51 ... 16 | 15  ...   0 |
175   values:   | V |    RES0    |  RDBase   |    ICID     |
176
177 where:
178
179 - V indicates whether the entry is valid. If not, other fields are
180   not meaningful.
181 - RES0: reserved field with Should-Be-Zero-or-Preserved behavior.
182 - RDBase is the PE number (GICR_TYPER.Processor_Number semantic),
183 - ICID is the collection ID
184
185 Interrupt Translation Entry (ITE)::
186
187   bits:     | 63 ... 48 | 47 ... 16 | 15 ... 0 |
188   values:   |    next   |   pINTID  |  ICID    |
189
190 where:
191
192 - next: equals to 0 if this entry is the last one; otherwise it corresponds
193   to the EventID offset to the next ITE capped by 2^16 -1.
194 - pINTID is the physical LPI ID; if zero, it means the entry is not valid
195   and other fields are not meaningful.
196 - ICID is the collection ID
197
198ITS Reset State:
199----------------
200
201RESET returns the ITS to the same state that it was when first created and
202initialized. When the RESET command returns, the following things are
203guaranteed:
204
205- The ITS is not enabled and quiescent
206  GITS_CTLR.Enabled = 0 .Quiescent=1
207- There is no internally cached state
208- No collection or device table are used
209  GITS_BASER<n>.Valid = 0
210- GITS_CBASER = 0, GITS_CREADR = 0, GITS_CWRITER = 0
211- The ABI version is unchanged and remains the one set when the ITS
212  device was first created.
213