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

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