Documentation/virtual/kvm/devices/arm-vgic-its.txt

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