1 ARM Virtual Generic Interrupt Controller (VGIC)
2 ===============================================
4 Device types supported:
5 KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0
6 KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0
7 KVM_DEV_TYPE_ARM_VGIC_ITS ARM Interrupt Translation Service Controller
9 Only one VGIC instance of the V2/V3 types above may be instantiated through
10 either this API or the legacy KVM_CREATE_IRQCHIP api. The created VGIC will
11 act as the VM interrupt controller, requiring emulated user-space devices to
12 inject interrupts to the VGIC instead of directly to CPUs.
14 Creating a guest GICv3 device requires a host GICv3 as well.
15 GICv3 implementations with hardware compatibility support allow a guest GICv2
18 Creating a virtual ITS controller requires a host GICv3 (but does not depend
19 on having physical ITS controllers).
20 There can be multiple ITS controllers per guest, each of them has to have
21 a separate, non-overlapping MMIO region.
24 KVM_DEV_ARM_VGIC_GRP_ADDR
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.
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.
36 KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit)
37 Base address in the guest physical address space of the GICv3 distributor
38 register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
39 This address needs to be 64K aligned and the region covers 64 KByte.
41 KVM_VGIC_V3_ADDR_TYPE_REDIST (rw, 64-bit)
42 Base address in the guest physical address space of the GICv3
43 redistributor register mappings. There are two 64K pages for each
44 VCPU and all of the redistributor pages are contiguous.
45 Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
46 This address needs to be 64K aligned.
48 KVM_VGIC_V3_ADDR_TYPE_ITS (rw, 64-bit)
49 Base address in the guest physical address space of the GICv3 ITS
50 control register frame. The ITS allows MSI(-X) interrupts to be
51 injected into guests. This extension is optional. If the kernel
52 does not support the ITS, the call returns -ENODEV.
53 Only valid for KVM_DEV_TYPE_ARM_VGIC_ITS.
54 This address needs to be 64K aligned and the region covers 128K.
56 KVM_DEV_ARM_VGIC_GRP_DIST_REGS
58 The attr field of kvm_device_attr encodes two values:
59 bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 |
60 values: | reserved | vcpu_index | offset |
62 All distributor regs are (rw, 32-bit)
64 The offset is relative to the "Distributor base address" as defined in the
65 GICv2 specs. Getting or setting such a register has the same effect as
66 reading or writing the register on the actual hardware from the cpu whose
67 index is specified with the vcpu_index field. Note that most distributor
68 fields are not banked, but return the same value regardless of the
69 vcpu_index used to access the register.
71 - Priorities are not implemented, and registers are RAZ/WI
72 - Currently only implemented for KVM_DEV_TYPE_ARM_VGIC_V2.
74 -ENXIO: Getting or setting this register is not yet supported
75 -EBUSY: One or more VCPUs are running
76 -EINVAL: Invalid vcpu_index supplied
78 KVM_DEV_ARM_VGIC_GRP_CPU_REGS
80 The attr field of kvm_device_attr encodes two values:
81 bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 |
82 values: | reserved | vcpu_index | offset |
84 All CPU interface regs are (rw, 32-bit)
86 The offset specifies the offset from the "CPU interface base address" as
87 defined in the GICv2 specs. Getting or setting such a register has the
88 same effect as reading or writing the register on the actual hardware.
90 The Active Priorities Registers APRn are implementation defined, so we set a
91 fixed format for our implementation that fits with the model of a "GICv2
92 implementation without the security extensions" which we present to the
93 guest. This interface always exposes four register APR[0-3] describing the
94 maximum possible 128 preemption levels. The semantics of the register
95 indicate if any interrupts in a given preemption level are in the active
96 state by setting the corresponding bit.
98 Thus, preemption level X has one or more active interrupts if and only if:
100 APRn[X mod 32] == 0b1, where n = X / 32
102 Bits for undefined preemption levels are RAZ/WI.
105 - Priorities are not implemented, and registers are RAZ/WI
106 - Currently only implemented for KVM_DEV_TYPE_ARM_VGIC_V2.
108 -ENXIO: Getting or setting this register is not yet supported
109 -EBUSY: One or more VCPUs are running
110 -EINVAL: Invalid vcpu_index supplied
112 KVM_DEV_ARM_VGIC_GRP_NR_IRQS
114 A value describing the number of interrupts (SGI, PPI and SPI) for
115 this GIC instance, ranging from 64 to 1024, in increments of 32.
118 -EINVAL: Value set is out of the expected range
119 -EBUSY: Value has already be set, or GIC has already been initialized
122 KVM_DEV_ARM_VGIC_GRP_CTRL
124 KVM_DEV_ARM_VGIC_CTRL_INIT
125 request the initialization of the VGIC or ITS, no additional parameter
126 in kvm_device_attr.addr.
128 -ENXIO: VGIC not properly configured as required prior to calling
130 -ENODEV: no online VCPU
131 -ENOMEM: memory shortage when allocating vgic internal data