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

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ==================================================
   4 ARM Virtual Generic Interrupt Controller v2 (VGIC)
   5 ==================================================
   6
   7 Device types supported:
   8
   9   - KVM_DEV_TYPE_ARM_VGIC_V2     ARM Generic Interrupt Controller v2.0
  10
  11 Only one VGIC instance may be instantiated through either this API or the
  12 legacy KVM_CREATE_IRQCHIP API.  The created VGIC will act as the VM interrupt
  13 controller, requiring emulated user-space devices to inject interrupts to the
  14 VGIC instead of directly to CPUs.
  15
  16 GICv3 implementations with hardware compatibility support allow creating a
  17 guest GICv2 through this interface.  For information on creating a guest GICv3
  18 device and guest ITS devices, see arm-vgic-v3.txt.  It is not possible to
  19 create both a GICv3 and GICv2 device on the same VM.
  20
  21
  22 Groups:
  23   KVM_DEV_ARM_VGIC_GRP_ADDR
  24    Attributes:
  25
  26     KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit)
  27       Base address in the guest physical address space of the GIC distributor
  28       register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
  29       This address needs to be 4K aligned and the region covers 4 KByte.
  30
  31     KVM_VGIC_V2_ADDR_TYPE_CPU (rw, 64-bit)
  32       Base address in the guest physical address space of the GIC virtual cpu
  33       interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
  34       This address needs to be 4K aligned and the region covers 4 KByte.
  35
  36   Errors:
  37
  38     =======  =============================================================
  39     -E2BIG   Address outside of addressable IPA range
  40     -EINVAL  Incorrectly aligned address
  41     -EEXIST  Address already configured
  42     -ENXIO   The group or attribute is unknown/unsupported for this device
  43              or hardware support is missing.
  44     -EFAULT  Invalid user pointer for attr->addr.
  45     =======  =============================================================
  46
  47   KVM_DEV_ARM_VGIC_GRP_DIST_REGS
  48    Attributes:
  49
  50     The attr field of kvm_device_attr encodes two values::
  51
  52       bits:     | 63   ....  40 | 39 ..  32  |  31   ....    0 |
  53       values:   |    reserved   | vcpu_index |      offset     |
  54
  55     All distributor regs are (rw, 32-bit)
  56
  57     The offset is relative to the "Distributor base address" as defined in the
  58     GICv2 specs.  Getting or setting such a register has the same effect as
  59     reading or writing the register on the actual hardware from the cpu whose
  60     index is specified with the vcpu_index field.  Note that most distributor
  61     fields are not banked, but return the same value regardless of the
  62     vcpu_index used to access the register.
  63
  64     GICD_IIDR.Revision is updated when the KVM implementation of an emulated
  65     GICv2 is changed in a way directly observable by the guest or userspace.
  66     Userspace should read GICD_IIDR from KVM and write back the read value to
  67     confirm its expected behavior is aligned with the KVM implementation.
  68     Userspace should set GICD_IIDR before setting any other registers (both
  69     KVM_DEV_ARM_VGIC_GRP_DIST_REGS and KVM_DEV_ARM_VGIC_GRP_CPU_REGS) to ensure
  70     the expected behavior. Unless GICD_IIDR has been set from userspace, writes
  71     to the interrupt group registers (GICD_IGROUPR) are ignored.
  72
  73   Errors:
  74
  75     =======  =====================================================
  76     -ENXIO   Getting or setting this register is not yet supported
  77     -EBUSY   One or more VCPUs are running
  78     -EINVAL  Invalid vcpu_index supplied
  79     =======  =====================================================
  80
  81   KVM_DEV_ARM_VGIC_GRP_CPU_REGS
  82    Attributes:
  83
  84     The attr field of kvm_device_attr encodes two values::
  85
  86       bits:     | 63   ....  40 | 39 ..  32  |  31   ....    0 |
  87       values:   |    reserved   | vcpu_index |      offset     |
  88
  89     All CPU interface regs are (rw, 32-bit)
  90
  91     The offset specifies the offset from the "CPU interface base address" as
  92     defined in the GICv2 specs.  Getting or setting such a register has the
  93     same effect as reading or writing the register on the actual hardware.
  94
  95     The Active Priorities Registers APRn are implementation defined, so we set a
  96     fixed format for our implementation that fits with the model of a "GICv2
  97     implementation without the security extensions" which we present to the
  98     guest.  This interface always exposes four register APR[0-3] describing the
  99     maximum possible 128 preemption levels.  The semantics of the register
 100     indicate if any interrupts in a given preemption level are in the active
 101     state by setting the corresponding bit.
 102
 103     Thus, preemption level X has one or more active interrupts if and only if:
 104
 105       APRn[X mod 32] == 0b1,  where n = X / 32
 106
 107     Bits for undefined preemption levels are RAZ/WI.
 108
 109     Note that this differs from a CPU's view of the APRs on hardware in which
 110     a GIC without the security extensions expose group 0 and group 1 active
 111     priorities in separate register groups, whereas we show a combined view
 112     similar to GICv2's GICH_APR.
 113
 114     For historical reasons and to provide ABI compatibility with userspace we
 115     export the GICC_PMR register in the format of the GICH_VMCR.VMPriMask
 116     field in the lower 5 bits of a word, meaning that userspace must always
 117     use the lower 5 bits to communicate with the KVM device and must shift the
 118     value left by 3 places to obtain the actual priority mask level.
 119
 120   Errors:
 121
 122     =======  =====================================================
 123     -ENXIO   Getting or setting this register is not yet supported
 124     -EBUSY   One or more VCPUs are running
 125     -EINVAL  Invalid vcpu_index supplied
 126     =======  =====================================================
 127
 128   KVM_DEV_ARM_VGIC_GRP_NR_IRQS
 129    Attributes:
 130
 131     A value describing the number of interrupts (SGI, PPI and SPI) for
 132     this GIC instance, ranging from 64 to 1024, in increments of 32.
 133
 134   Errors:
 135
 136     =======  =============================================================
 137     -EINVAL  Value set is out of the expected range
 138     -EBUSY   Value has already be set, or GIC has already been initialized
 139              with default values.
 140     =======  =============================================================
 141
 142   KVM_DEV_ARM_VGIC_GRP_CTRL
 143    Attributes:
 144
 145     KVM_DEV_ARM_VGIC_CTRL_INIT
 146       request the initialization of the VGIC or ITS, no additional parameter
 147       in kvm_device_attr.addr.
 148
 149   Errors:
 150
 151     =======  =========================================================
 152     -ENXIO   VGIC not properly configured as required prior to calling
 153              this attribute
 154     -ENODEV  no online VCPU
 155     -ENOMEM  memory shortage when allocating vgic internal data
 156     =======  =========================================================