arm-vgic.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3==================================================
  4ARM Virtual Generic Interrupt Controller v2 (VGIC)
  5==================================================
  6
  7Device types supported:
  8
  9  - KVM_DEV_TYPE_ARM_VGIC_V2     ARM Generic Interrupt Controller v2.0
 10
 11Only one VGIC instance may be instantiated through either this API or the
 12legacy KVM_CREATE_IRQCHIP API.  The created VGIC will act as the VM interrupt
 13controller, requiring emulated user-space devices to inject interrupts to the
 14VGIC instead of directly to CPUs.
 15
 16GICv3 implementations with hardware compatibility support allow creating a
 17guest GICv2 through this interface.  For information on creating a guest GICv3
 18device and guest ITS devices, see arm-vgic-v3.txt.  It is not possible to
 19create both a GICv3 and GICv2 device on the same VM.
 20
 21
 22Groups:
 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 8 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    =======  =========================================================