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