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   Errors:
  31     -E2BIG:  Address outside of addressable IPA range
  32     -EINVAL: Incorrectly aligned address
  33     -EEXIST: Address already configured
  34     -ENXIO:  The group or attribute is unknown/unsupported for this device
  35              or hardware support is missing.
  36     -EFAULT: Invalid user pointer for attr->addr.
  37
  38
  39
  40   KVM_DEV_ARM_VGIC_GRP_DIST_REGS
  41   KVM_DEV_ARM_VGIC_GRP_REDIST_REGS
  42   Attributes:
  43     The attr field of kvm_device_attr encodes two values:
  44     bits:     | 63   ....  32  |  31   ....    0 |
  45     values:   |      mpidr     |      offset     |
  46
  47     All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a
  48     __u32 value.  64-bit registers must be accessed by separately accessing the
  49     lower and higher word.
  50
  51     Writes to read-only registers are ignored by the kernel.
  52
  53     KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers.
  54     KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU
  55     specified by the mpidr.
  56
  57     The offset is relative to the "[Re]Distributor base address" as defined
  58     in the GICv3/4 specs.  Getting or setting such a register has the same
  59     effect as reading or writing the register on real hardware, except for the
  60     following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR,
  61     GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0.  These registers behave
  62     differently when accessed via this interface compared to their
  63     architecturally defined behavior to allow software a full view of the
  64     VGIC's internal state.
  65
  66     The mpidr field is used to specify which
  67     redistributor is accessed.  The mpidr is ignored for the distributor.
  68
  69     The mpidr encoding is based on the affinity information in the
  70     architecture defined MPIDR, and the field is encoded as follows:
  71       | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
  72       |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
  73
  74     Note that distributor fields are not banked, but return the same value
  75     regardless of the mpidr used to access the register.
  76
  77     The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such
  78     that a write of a clear bit has no effect, whereas a write with a set bit
  79     clears that value.  To allow userspace to freely set the values of these two
  80     registers, setting the attributes with the register offsets for these two
  81     registers simply sets the non-reserved bits to the value written.
  82
  83
  84     Accesses (reads and writes) to the GICD_ISPENDR register region and
  85     GICR_ISPENDR0 registers get/set the value of the latched pending state for
  86     the interrupts.
  87
  88     This is identical to the value returned by a guest read from ISPENDR for an
  89     edge triggered interrupt, but may differ for level triggered interrupts.
  90     For edge triggered interrupts, once an interrupt becomes pending (whether
  91     because of an edge detected on the input line or because of a guest write
  92     to ISPENDR) this state is "latched", and only cleared when either the
  93     interrupt is activated or when the guest writes to ICPENDR. A level
  94     triggered interrupt may be pending either because the level input is held
  95     high by a device, or because of a guest write to the ISPENDR register. Only
  96     ISPENDR writes are latched; if the device lowers the line level then the
  97     interrupt is no longer pending unless the guest also wrote to ISPENDR, and
  98     conversely writes to ICPENDR or activations of the interrupt do not clear
  99     the pending status if the line level is still being held high.  (These
 100     rules are documented in the GICv3 specification descriptions of the ICPENDR
 101     and ISPENDR registers.) For a level triggered interrupt the value accessed
 102     here is that of the latch which is set by ISPENDR and cleared by ICPENDR or
 103     interrupt activation, whereas the value returned by a guest read from
 104     ISPENDR is the logical OR of the latch value and the input line level.
 105
 106     Raw access to the latch state is provided to userspace so that it can save
 107     and restore the entire GIC internal state (which is defined by the
 108     combination of the current input line level and the latch state, and cannot
 109     be deduced from purely the line level and the value of the ISPENDR
 110     registers).
 111
 112     Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have
 113     RAZ/WI semantics, meaning that reads always return 0 and writes are always
 114     ignored.
 115
 116   Errors:
 117     -ENXIO: Getting or setting this register is not yet supported
 118     -EBUSY: One or more VCPUs are running
 119
 120
 121   KVM_DEV_ARM_VGIC_CPU_SYSREGS
 122   Attributes:
 123     The attr field of kvm_device_attr encodes two values:
 124     bits:     | 63      ....       32 | 31  ....  16 | 15  ....  0 |
 125     values:   |         mpidr         |      RES     |    instr    |
 126
 127     The mpidr field encodes the CPU ID based on the affinity information in the
 128     architecture defined MPIDR, and the field is encoded as follows:
 129       | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
 130       |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
 131
 132     The instr field encodes the system register to access based on the fields
 133     defined in the A64 instruction set encoding for system register access
 134     (RES means the bits are reserved for future use and should be zero):
 135
 136       | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 |
 137       |   Op 0    |    Op1    |    CRn   |   CRm   |   Op2   |
 138
 139     All system regs accessed through this API are (rw, 64-bit) and
 140     kvm_device_attr.addr points to a __u64 value.
 141
 142     KVM_DEV_ARM_VGIC_CPU_SYSREGS accesses the CPU interface registers for the
 143     CPU specified by the mpidr field.
 144
 145   Errors:
 146     -ENXIO: Getting or setting this register is not yet supported
 147     -EBUSY: VCPU is running
 148     -EINVAL: Invalid mpidr supplied
 149
 150
 151   KVM_DEV_ARM_VGIC_GRP_NR_IRQS
 152   Attributes:
 153     A value describing the number of interrupts (SGI, PPI and SPI) for
 154     this GIC instance, ranging from 64 to 1024, in increments of 32.
 155
 156     kvm_device_attr.addr points to a __u32 value.
 157
 158   Errors:
 159     -EINVAL: Value set is out of the expected range
 160     -EBUSY: Value has already be set.
 161
 162
 163   KVM_DEV_ARM_VGIC_GRP_CTRL
 164   Attributes:
 165     KVM_DEV_ARM_VGIC_CTRL_INIT
 166       request the initialization of the VGIC, no additional parameter in
 167       kvm_device_attr.addr.
 168   Errors:
 169     -ENXIO: VGIC not properly configured as required prior to calling
 170      this attribute
 171     -ENODEV: no online VCPU
 172     -ENOMEM: memory shortage when allocating vgic internal data
 173
 174
 175   KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO
 176   Attributes:
 177     The attr field of kvm_device_attr encodes the following values:
 178     bits:     | 63      ....       32 | 31   ....    10 | 9  ....  0 |
 179     values:   |         mpidr         |      info       |   vINTID   |
 180
 181     The vINTID specifies which set of IRQs is reported on.
 182
 183     The info field specifies which information userspace wants to get or set
 184     using this interface.  Currently we support the following info values:
 185
 186       VGIC_LEVEL_INFO_LINE_LEVEL:
 187         Get/Set the input level of the IRQ line for a set of 32 contiguously
 188         numbered interrupts.
 189         vINTID must be a multiple of 32.
 190
 191         kvm_device_attr.addr points to a __u32 value which will contain a
 192         bitmap where a set bit means the interrupt level is asserted.
 193
 194         Bit[n] indicates the status for interrupt vINTID + n.
 195
 196     SGIs and any interrupt with a higher ID than the number of interrupts
 197     supported, will be RAZ/WI.  LPIs are always edge-triggered and are
 198     therefore not supported by this interface.
 199
 200     PPIs are reported per VCPU as specified in the mpidr field, and SPIs are
 201     reported with the same value regardless of the mpidr specified.
 202
 203     The mpidr field encodes the CPU ID based on the affinity information in the
 204     architecture defined MPIDR, and the field is encoded as follows:
 205       | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
 206       |    Aff3    |    Aff2    |    Aff1    |    Aff0    |