Documentation/virt/kvm/devices/arm-vgic-its.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===============================================
   4 ARM Virtual Interrupt Translation Service (ITS)
   5 ===============================================
   6
   7 Device types supported:
   8   KVM_DEV_TYPE_ARM_VGIC_ITS    ARM Interrupt Translation Service Controller
   9
  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.
  13
  14 There can be multiple ITS controllers per guest, each of them has to have
  15 a separate, non-overlapping MMIO region.
  16
  17
  18 Groups
  19 ======
  20
  21 KVM_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
  41 KVM_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
  89 KVM_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
 126 ITS Restore Sequence:
 127 ---------------------
 128
 129 The following ordering must be followed when restoring the GIC and the ITS:
 130
 131 a) restore all guest memory and create vcpus
 132 b) restore all redistributors
 133 c) provide the ITS base address
 134    (KVM_DEV_ARM_VGIC_GRP_ADDR)
 135 d) 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
 142 Then vcpus can be started.
 143
 144 ITS 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
 198 ITS Reset State:
 199 ----------------
 200
 201 RESET returns the ITS to the same state that it was when first created and
 202 initialized. When the RESET command returns, the following things are
 203 guaranteed:
 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.