0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===============================================
0004 ARM Virtual Interrupt Translation Service (ITS)
0005 ===============================================
0006
0007 Device types supported:
0008 KVM_DEV_TYPE_ARM_VGIC_ITS ARM Interrupt Translation Service Controller
0009
0010 The ITS allows MSI(-X) interrupts to be injected into guests. This extension is
0011 optional. Creating a virtual ITS controller also requires a host GICv3 (see
0012 arm-vgic-v3.txt), but does not depend on having physical ITS controllers.
0013
0014 There can be multiple ITS controllers per guest, each of them has to have
0015 a separate, non-overlapping MMIO region.
0016
0017
0018 Groups
0019 ======
0020
0021 KVM_DEV_ARM_VGIC_GRP_ADDR
0022 -------------------------
0023
0024 Attributes:
0025 KVM_VGIC_ITS_ADDR_TYPE (rw, 64-bit)
0026 Base address in the guest physical address space of the GICv3 ITS
0027 control register frame.
0028 This address needs to be 64K aligned and the region covers 128K.
0029
0030 Errors:
0031
0032 ======= =================================================
0033 -E2BIG Address outside of addressable IPA range
0034 -EINVAL Incorrectly aligned address
0035 -EEXIST Address already configured
0036 -EFAULT Invalid user pointer for attr->addr.
0037 -ENODEV Incorrect attribute or the ITS is not supported.
0038 ======= =================================================
0039
0040
0041 KVM_DEV_ARM_VGIC_GRP_CTRL
0042 -------------------------
0043
0044 Attributes:
0045 KVM_DEV_ARM_VGIC_CTRL_INIT
0046 request the initialization of the ITS, no additional parameter in
0047 kvm_device_attr.addr.
0048
0049 KVM_DEV_ARM_ITS_CTRL_RESET
0050 reset the ITS, no additional parameter in kvm_device_attr.addr.
0051 See "ITS Reset State" section.
0052
0053 KVM_DEV_ARM_ITS_SAVE_TABLES
0054 save the ITS table data into guest RAM, at the location provisioned
0055 by the guest in corresponding registers/table entries.
0056
0057 The layout of the tables in guest memory defines an ABI. The entries
0058 are laid out in little endian format as described in the last paragraph.
0059
0060 KVM_DEV_ARM_ITS_RESTORE_TABLES
0061 restore the ITS tables from guest RAM to ITS internal structures.
0062
0063 The GICV3 must be restored before the ITS and all ITS registers but
0064 the GITS_CTLR must be restored before restoring the ITS tables.
0065
0066 The GITS_IIDR read-only register must also be restored before
0067 calling KVM_DEV_ARM_ITS_RESTORE_TABLES as the IIDR revision field
0068 encodes the ABI revision.
0069
0070 The expected ordering when restoring the GICv3/ITS is described in section
0071 "ITS Restore Sequence".
0072
0073 Errors:
0074
0075 ======= ==========================================================
0076 -ENXIO ITS not properly configured as required prior to setting
0077 this attribute
0078 -ENOMEM Memory shortage when allocating ITS internal data
0079 -EINVAL Inconsistent restored data
0080 -EFAULT Invalid guest ram access
0081 -EBUSY One or more VCPUS are running
0082 -EACCES The virtual ITS is backed by a physical GICv4 ITS, and the
0083 state is not available without GICv4.1
0084 ======= ==========================================================
0085
0086 KVM_DEV_ARM_VGIC_GRP_ITS_REGS
0087 -----------------------------
0088
0089 Attributes:
0090 The attr field of kvm_device_attr encodes the offset of the
0091 ITS register, relative to the ITS control frame base address
0092 (ITS_base).
0093
0094 kvm_device_attr.addr points to a __u64 value whatever the width
0095 of the addressed register (32/64 bits). 64 bit registers can only
0096 be accessed with full length.
0097
0098 Writes to read-only registers are ignored by the kernel except for:
0099
0100 - GITS_CREADR. It must be restored otherwise commands in the queue
0101 will be re-executed after restoring CWRITER. GITS_CREADR must be
0102 restored before restoring the GITS_CTLR which is likely to enable the
0103 ITS. Also it must be restored after GITS_CBASER since a write to
0104 GITS_CBASER resets GITS_CREADR.
0105 - GITS_IIDR. The Revision field encodes the table layout ABI revision.
0106 In the future we might implement direct injection of virtual LPIs.
0107 This will require an upgrade of the table layout and an evolution of
0108 the ABI. GITS_IIDR must be restored before calling
0109 KVM_DEV_ARM_ITS_RESTORE_TABLES.
0110
0111 For other registers, getting or setting a register has the same
0112 effect as reading/writing the register on real hardware.
0113
0114 Errors:
0115
0116 ======= ====================================================
0117 -ENXIO Offset does not correspond to any supported register
0118 -EFAULT Invalid user pointer for attr->addr
0119 -EINVAL Offset is not 64-bit aligned
0120 -EBUSY one or more VCPUS are running
0121 ======= ====================================================
0122
0123 ITS Restore Sequence:
0124 ---------------------
0125
0126 The following ordering must be followed when restoring the GIC and the ITS:
0127
0128 a) restore all guest memory and create vcpus
0129 b) restore all redistributors
0130 c) provide the ITS base address
0131 (KVM_DEV_ARM_VGIC_GRP_ADDR)
0132 d) restore the ITS in the following order:
0133
0134 1. Restore GITS_CBASER
0135 2. Restore all other ``GITS_`` registers, except GITS_CTLR!
0136 3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES)
0137 4. Restore GITS_CTLR
0138
0139 Then vcpus can be started.
0140
0141 ITS Table ABI REV0:
0142 -------------------
0143
0144 Revision 0 of the ABI only supports the features of a virtual GICv3, and does
0145 not support a virtual GICv4 with support for direct injection of virtual
0146 interrupts for nested hypervisors.
0147
0148 The device table and ITT are indexed by the DeviceID and EventID,
0149 respectively. The collection table is not indexed by CollectionID, and the
0150 entries in the collection are listed in no particular order.
0151 All entries are 8 bytes.
0152
0153 Device Table Entry (DTE)::
0154
0155 bits: | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 |
0156 values: | V | next | ITT_addr | Size |
0157
0158 where:
0159
0160 - V indicates whether the entry is valid. If not, other fields
0161 are not meaningful.
0162 - next: equals to 0 if this entry is the last one; otherwise it
0163 corresponds to the DeviceID offset to the next DTE, capped by
0164 2^14 -1.
0165 - ITT_addr matches bits [51:8] of the ITT address (256 Byte aligned).
0166 - Size specifies the supported number of bits for the EventID,
0167 minus one
0168
0169 Collection Table Entry (CTE)::
0170
0171 bits: | 63| 62 .. 52 | 51 ... 16 | 15 ... 0 |
0172 values: | V | RES0 | RDBase | ICID |
0173
0174 where:
0175
0176 - V indicates whether the entry is valid. If not, other fields are
0177 not meaningful.
0178 - RES0: reserved field with Should-Be-Zero-or-Preserved behavior.
0179 - RDBase is the PE number (GICR_TYPER.Processor_Number semantic),
0180 - ICID is the collection ID
0181
0182 Interrupt Translation Entry (ITE)::
0183
0184 bits: | 63 ... 48 | 47 ... 16 | 15 ... 0 |
0185 values: | next | pINTID | ICID |
0186
0187 where:
0188
0189 - next: equals to 0 if this entry is the last one; otherwise it corresponds
0190 to the EventID offset to the next ITE capped by 2^16 -1.
0191 - pINTID is the physical LPI ID; if zero, it means the entry is not valid
0192 and other fields are not meaningful.
0193 - ICID is the collection ID
0194
0195 ITS Reset State:
0196 ----------------
0197
0198 RESET returns the ITS to the same state that it was when first created and
0199 initialized. When the RESET command returns, the following things are
0200 guaranteed:
0201
0202 - The ITS is not enabled and quiescent
0203 GITS_CTLR.Enabled = 0 .Quiescent=1
0204 - There is no internally cached state
0205 - No collection or device table are used
0206 GITS_BASER<n>.Valid = 0
0207 - GITS_CBASER = 0, GITS_CREADR = 0, GITS_CWRITER = 0
0208 - The ABI version is unchanged and remains the one set when the ITS
0209 device was first created.
