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

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ==============================================================
   4 ARM Virtual Generic Interrupt Controller v3 and later (VGICv3)
   5 ==============================================================
   6
   7
   8 Device types supported:
   9   - KVM_DEV_TYPE_ARM_VGIC_V3     ARM Generic Interrupt Controller v3.0
  10
  11 Only one VGIC instance may be instantiated through this API.  The created VGIC
  12 will act as the VM interrupt controller, requiring emulated user-space devices
  13 to inject interrupts to the VGIC instead of directly to CPUs.  It is not
  14 possible to create both a GICv3 and GICv2 on the same VM.
  15
  16 Creating a guest GICv3 device requires a host GICv3 as well.
  17
  18
  19 Groups:
  20   KVM_DEV_ARM_VGIC_GRP_ADDR
  21    Attributes:
  22
  23     KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit)
  24       Base address in the guest physical address space of the GICv3 distributor
  25       register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
  26       This address needs to be 64K aligned and the region covers 64 KByte.
  27
  28     KVM_VGIC_V3_ADDR_TYPE_REDIST (rw, 64-bit)
  29       Base address in the guest physical address space of the GICv3
  30       redistributor register mappings. There are two 64K pages for each
  31       VCPU and all of the redistributor pages are contiguous.
  32       Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
  33       This address needs to be 64K aligned.
  34
  35     KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION (rw, 64-bit)
  36       The attribute data pointed to by kvm_device_attr.addr is a __u64 value::
  37
  38         bits:     | 63   ....  52  |  51   ....   16 | 15 - 12  |11 - 0
  39         values:   |     count      |       base      |  flags   | index
  40
  41       - index encodes the unique redistributor region index
  42       - flags: reserved for future use, currently 0
  43       - base field encodes bits [51:16] of the guest physical base address
  44         of the first redistributor in the region.
  45       - count encodes the number of redistributors in the region. Must be
  46         greater than 0.
  47
  48       There are two 64K pages for each redistributor in the region and
  49       redistributors are laid out contiguously within the region. Regions
  50       are filled with redistributors in the index order. The sum of all
  51       region count fields must be greater than or equal to the number of
  52       VCPUs. Redistributor regions must be registered in the incremental
  53       index order, starting from index 0.
  54
  55       The characteristics of a specific redistributor region can be read
  56       by presetting the index field in the attr data.
  57       Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
  58
  59   It is invalid to mix calls with KVM_VGIC_V3_ADDR_TYPE_REDIST and
  60   KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes.
  61
  62   Note that to obtain reproducible results (the same VCPU being associated
  63   with the same redistributor across a save/restore operation), VCPU creation
  64   order, redistributor region creation order as well as the respective
  65   interleaves of VCPU and region creation MUST be preserved.  Any change in
  66   either ordering may result in a different vcpu_id/redistributor association,
  67   resulting in a VM that will fail to run at restore time.
  68
  69   Errors:
  70
  71     =======  =============================================================
  72     -E2BIG   Address outside of addressable IPA range
  73     -EINVAL  Incorrectly aligned address, bad redistributor region
  74              count/index, mixed redistributor region attribute usage
  75     -EEXIST  Address already configured
  76     -ENOENT  Attempt to read the characteristics of a non existing
  77              redistributor region
  78     -ENXIO   The group or attribute is unknown/unsupported for this device
  79              or hardware support is missing.
  80     -EFAULT  Invalid user pointer for attr->addr.
  81     =======  =============================================================
  82
  83
  84   KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS
  85    Attributes:
  86
  87     The attr field of kvm_device_attr encodes two values::
  88
  89       bits:     | 63   ....  32  |  31   ....    0 |
  90       values:   |      mpidr     |      offset     |
  91
  92     All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a
  93     __u32 value.  64-bit registers must be accessed by separately accessing the
  94     lower and higher word.
  95
  96     Writes to read-only registers are ignored by the kernel.
  97
  98     KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers.
  99     KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU
 100     specified by the mpidr.
 101
 102     The offset is relative to the "[Re]Distributor base address" as defined
 103     in the GICv3/4 specs.  Getting or setting such a register has the same
 104     effect as reading or writing the register on real hardware, except for the
 105     following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR,
 106     GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0.  These registers behave
 107     differently when accessed via this interface compared to their
 108     architecturally defined behavior to allow software a full view of the
 109     VGIC's internal state.
 110
 111     The mpidr field is used to specify which
 112     redistributor is accessed.  The mpidr is ignored for the distributor.
 113
 114     The mpidr encoding is based on the affinity information in the
 115     architecture defined MPIDR, and the field is encoded as follows::
 116
 117       | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
 118       |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
 119
 120     Note that distributor fields are not banked, but return the same value
 121     regardless of the mpidr used to access the register.
 122
 123     GICD_IIDR.Revision is updated when the KVM implementation is changed in a
 124     way directly observable by the guest or userspace.  Userspace should read
 125     GICD_IIDR from KVM and write back the read value to confirm its expected
 126     behavior is aligned with the KVM implementation.  Userspace should set
 127     GICD_IIDR before setting any other registers to ensure the expected
 128     behavior.
 129
 130
 131     The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such
 132     that a write of a clear bit has no effect, whereas a write with a set bit
 133     clears that value.  To allow userspace to freely set the values of these two
 134     registers, setting the attributes with the register offsets for these two
 135     registers simply sets the non-reserved bits to the value written.
 136
 137
 138     Accesses (reads and writes) to the GICD_ISPENDR register region and
 139     GICR_ISPENDR0 registers get/set the value of the latched pending state for
 140     the interrupts.
 141
 142     This is identical to the value returned by a guest read from ISPENDR for an
 143     edge triggered interrupt, but may differ for level triggered interrupts.
 144     For edge triggered interrupts, once an interrupt becomes pending (whether
 145     because of an edge detected on the input line or because of a guest write
 146     to ISPENDR) this state is "latched", and only cleared when either the
 147     interrupt is activated or when the guest writes to ICPENDR. A level
 148     triggered interrupt may be pending either because the level input is held
 149     high by a device, or because of a guest write to the ISPENDR register. Only
 150     ISPENDR writes are latched; if the device lowers the line level then the
 151     interrupt is no longer pending unless the guest also wrote to ISPENDR, and
 152     conversely writes to ICPENDR or activations of the interrupt do not clear
 153     the pending status if the line level is still being held high.  (These
 154     rules are documented in the GICv3 specification descriptions of the ICPENDR
 155     and ISPENDR registers.) For a level triggered interrupt the value accessed
 156     here is that of the latch which is set by ISPENDR and cleared by ICPENDR or
 157     interrupt activation, whereas the value returned by a guest read from
 158     ISPENDR is the logical OR of the latch value and the input line level.
 159
 160     Raw access to the latch state is provided to userspace so that it can save
 161     and restore the entire GIC internal state (which is defined by the
 162     combination of the current input line level and the latch state, and cannot
 163     be deduced from purely the line level and the value of the ISPENDR
 164     registers).
 165
 166     Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have
 167     RAZ/WI semantics, meaning that reads always return 0 and writes are always
 168     ignored.
 169
 170   Errors:
 171
 172     ======  =====================================================
 173     -ENXIO  Getting or setting this register is not yet supported
 174     -EBUSY  One or more VCPUs are running
 175     ======  =====================================================
 176
 177
 178   KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS
 179    Attributes:
 180
 181     The attr field of kvm_device_attr encodes two values::
 182
 183       bits:     | 63      ....       32 | 31  ....  16 | 15  ....  0 |
 184       values:   |         mpidr         |      RES     |    instr    |
 185
 186     The mpidr field encodes the CPU ID based on the affinity information in the
 187     architecture defined MPIDR, and the field is encoded as follows::
 188
 189       | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
 190       |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
 191
 192     The instr field encodes the system register to access based on the fields
 193     defined in the A64 instruction set encoding for system register access
 194     (RES means the bits are reserved for future use and should be zero)::
 195
 196       | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 |
 197       |   Op 0    |    Op1    |    CRn   |   CRm   |   Op2   |
 198
 199     All system regs accessed through this API are (rw, 64-bit) and
 200     kvm_device_attr.addr points to a __u64 value.
 201
 202     KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the
 203     CPU specified by the mpidr field.
 204
 205     CPU interface registers access is not implemented for AArch32 mode.
 206     Error -ENXIO is returned when accessed in AArch32 mode.
 207
 208   Errors:
 209
 210     =======  =====================================================
 211     -ENXIO   Getting or setting this register is not yet supported
 212     -EBUSY   VCPU is running
 213     -EINVAL  Invalid mpidr or register value supplied
 214     =======  =====================================================
 215
 216
 217   KVM_DEV_ARM_VGIC_GRP_NR_IRQS
 218    Attributes:
 219
 220     A value describing the number of interrupts (SGI, PPI and SPI) for
 221     this GIC instance, ranging from 64 to 1024, in increments of 32.
 222
 223     kvm_device_attr.addr points to a __u32 value.
 224
 225   Errors:
 226
 227     =======  ======================================
 228     -EINVAL  Value set is out of the expected range
 229     -EBUSY   Value has already be set.
 230     =======  ======================================
 231
 232
 233   KVM_DEV_ARM_VGIC_GRP_CTRL
 234    Attributes:
 235
 236     KVM_DEV_ARM_VGIC_CTRL_INIT
 237       request the initialization of the VGIC, no additional parameter in
 238       kvm_device_attr.addr. Must be called after all VCPUs have been created.
 239     KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES
 240       save all LPI pending bits into guest RAM pending tables.
 241
 242       The first kB of the pending table is not altered by this operation.
 243
 244   Errors:
 245
 246     =======  ========================================================
 247     -ENXIO   VGIC not properly configured as required prior to calling
 248              this attribute
 249     -ENODEV  no online VCPU
 250     -ENOMEM  memory shortage when allocating vgic internal data
 251     -EFAULT  Invalid guest ram access
 252     -EBUSY   One or more VCPUS are running
 253     =======  ========================================================
 254
 255
 256   KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO
 257    Attributes:
 258
 259     The attr field of kvm_device_attr encodes the following values::
 260
 261       bits:     | 63      ....       32 | 31   ....    10 | 9  ....  0 |
 262       values:   |         mpidr         |      info       |   vINTID   |
 263
 264     The vINTID specifies which set of IRQs is reported on.
 265
 266     The info field specifies which information userspace wants to get or set
 267     using this interface.  Currently we support the following info values:
 268
 269       VGIC_LEVEL_INFO_LINE_LEVEL:
 270         Get/Set the input level of the IRQ line for a set of 32 contiguously
 271         numbered interrupts.
 272
 273         vINTID must be a multiple of 32.
 274
 275         kvm_device_attr.addr points to a __u32 value which will contain a
 276         bitmap where a set bit means the interrupt level is asserted.
 277
 278         Bit[n] indicates the status for interrupt vINTID + n.
 279
 280     SGIs and any interrupt with a higher ID than the number of interrupts
 281     supported, will be RAZ/WI.  LPIs are always edge-triggered and are
 282     therefore not supported by this interface.
 283
 284     PPIs are reported per VCPU as specified in the mpidr field, and SPIs are
 285     reported with the same value regardless of the mpidr specified.
 286
 287     The mpidr field encodes the CPU ID based on the affinity information in the
 288     architecture defined MPIDR, and the field is encoded as follows::
 289
 290       | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
 291       |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
 292
 293   Errors:
 294
 295     =======  =============================================
 296     -EINVAL  vINTID is not multiple of 32 or info field is
 297              not VGIC_LEVEL_INFO_LINE_LEVEL
 298     =======  =============================================