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

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