tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1ARM Virtual Generic Interrupt Controller v3 and later (VGICv3)
2==============================================================
3
4
5Device types supported:
6 KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0
7
8Only one VGIC instance may be instantiated through this API. The created VGIC
9will act as the VM interrupt controller, requiring emulated user-space devices
10to inject interrupts to the VGIC instead of directly to CPUs. It is not
11possible to create both a GICv3 and GICv2 on the same VM.
12
13Creating a guest GICv3 device requires a host GICv3 as well.
14
15
16Groups:
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
31 KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION (rw, 64-bit)
32 The attribute data pointed to by kvm_device_attr.addr is a __u64 value:
33 bits: | 63 .... 52 | 51 .... 16 | 15 - 12 |11 - 0
34 values: | count | base | flags | index
35 - index encodes the unique redistributor region index
36 - flags: reserved for future use, currently 0
37 - base field encodes bits [51:16] of the guest physical base address
38 of the first redistributor in the region.
39 - count encodes the number of redistributors in the region. Must be
40 greater than 0.
41 There are two 64K pages for each redistributor in the region and
42 redistributors are laid out contiguously within the region. Regions
43 are filled with redistributors in the index order. The sum of all
44 region count fields must be greater than or equal to the number of
45 VCPUs. Redistributor regions must be registered in the incremental
46 index order, starting from index 0.
47 The characteristics of a specific redistributor region can be read
48 by presetting the index field in the attr data.
49 Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
50
51 It is invalid to mix calls with KVM_VGIC_V3_ADDR_TYPE_REDIST and
52 KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes.
53
54 Errors:
55 -E2BIG: Address outside of addressable IPA range
56 -EINVAL: Incorrectly aligned address, bad redistributor region
57 count/index, mixed redistributor region attribute usage
58 -EEXIST: Address already configured
59 -ENOENT: Attempt to read the characteristics of a non existing
60 redistributor region
61 -ENXIO: The group or attribute is unknown/unsupported for this device
62 or hardware support is missing.
63 -EFAULT: Invalid user pointer for attr->addr.
64
65
66 KVM_DEV_ARM_VGIC_GRP_DIST_REGS
67 KVM_DEV_ARM_VGIC_GRP_REDIST_REGS
68 Attributes:
69 The attr field of kvm_device_attr encodes two values:
70 bits: | 63 .... 32 | 31 .... 0 |
71 values: | mpidr | offset |
72
73 All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a
74 __u32 value. 64-bit registers must be accessed by separately accessing the
75 lower and higher word.
76
77 Writes to read-only registers are ignored by the kernel.
78
79 KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers.
80 KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU
81 specified by the mpidr.
82
83 The offset is relative to the "[Re]Distributor base address" as defined
84 in the GICv3/4 specs. Getting or setting such a register has the same
85 effect as reading or writing the register on real hardware, except for the
86 following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR,
87 GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0. These registers behave
88 differently when accessed via this interface compared to their
89 architecturally defined behavior to allow software a full view of the
90 VGIC's internal state.
91
92 The mpidr field is used to specify which
93 redistributor is accessed. The mpidr is ignored for the distributor.
94
95 The mpidr encoding is based on the affinity information in the
96 architecture defined MPIDR, and the field is encoded as follows:
97 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
98 | Aff3 | Aff2 | Aff1 | Aff0 |
99
100 Note that distributor fields are not banked, but return the same value
101 regardless of the mpidr used to access the register.
102
103 The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such
104 that a write of a clear bit has no effect, whereas a write with a set bit
105 clears that value. To allow userspace to freely set the values of these two
106 registers, setting the attributes with the register offsets for these two
107 registers simply sets the non-reserved bits to the value written.
108
109
110 Accesses (reads and writes) to the GICD_ISPENDR register region and
111 GICR_ISPENDR0 registers get/set the value of the latched pending state for
112 the interrupts.
113
114 This is identical to the value returned by a guest read from ISPENDR for an
115 edge triggered interrupt, but may differ for level triggered interrupts.
116 For edge triggered interrupts, once an interrupt becomes pending (whether
117 because of an edge detected on the input line or because of a guest write
118 to ISPENDR) this state is "latched", and only cleared when either the
119 interrupt is activated or when the guest writes to ICPENDR. A level
120 triggered interrupt may be pending either because the level input is held
121 high by a device, or because of a guest write to the ISPENDR register. Only
122 ISPENDR writes are latched; if the device lowers the line level then the
123 interrupt is no longer pending unless the guest also wrote to ISPENDR, and
124 conversely writes to ICPENDR or activations of the interrupt do not clear
125 the pending status if the line level is still being held high. (These
126 rules are documented in the GICv3 specification descriptions of the ICPENDR
127 and ISPENDR registers.) For a level triggered interrupt the value accessed
128 here is that of the latch which is set by ISPENDR and cleared by ICPENDR or
129 interrupt activation, whereas the value returned by a guest read from
130 ISPENDR is the logical OR of the latch value and the input line level.
131
132 Raw access to the latch state is provided to userspace so that it can save
133 and restore the entire GIC internal state (which is defined by the
134 combination of the current input line level and the latch state, and cannot
135 be deduced from purely the line level and the value of the ISPENDR
136 registers).
137
138 Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have
139 RAZ/WI semantics, meaning that reads always return 0 and writes are always
140 ignored.
141
142 Errors:
143 -ENXIO: Getting or setting this register is not yet supported
144 -EBUSY: One or more VCPUs are running
145
146
147 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS
148 Attributes:
149 The attr field of kvm_device_attr encodes two values:
150 bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 |
151 values: | mpidr | RES | instr |
152
153 The mpidr field encodes the CPU ID based on the affinity information in the
154 architecture defined MPIDR, and the field is encoded as follows:
155 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
156 | Aff3 | Aff2 | Aff1 | Aff0 |
157
158 The instr field encodes the system register to access based on the fields
159 defined in the A64 instruction set encoding for system register access
160 (RES means the bits are reserved for future use and should be zero):
161
162 | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 |
163 | Op 0 | Op1 | CRn | CRm | Op2 |
164
165 All system regs accessed through this API are (rw, 64-bit) and
166 kvm_device_attr.addr points to a __u64 value.
167
168 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the
169 CPU specified by the mpidr field.
170
171 CPU interface registers access is not implemented for AArch32 mode.
172 Error -ENXIO is returned when accessed in AArch32 mode.
173 Errors:
174 -ENXIO: Getting or setting this register is not yet supported
175 -EBUSY: VCPU is running
176 -EINVAL: Invalid mpidr or register value supplied
177
178
179 KVM_DEV_ARM_VGIC_GRP_NR_IRQS
180 Attributes:
181 A value describing the number of interrupts (SGI, PPI and SPI) for
182 this GIC instance, ranging from 64 to 1024, in increments of 32.
183
184 kvm_device_attr.addr points to a __u32 value.
185
186 Errors:
187 -EINVAL: Value set is out of the expected range
188 -EBUSY: Value has already be set.
189
190
191 KVM_DEV_ARM_VGIC_GRP_CTRL
192 Attributes:
193 KVM_DEV_ARM_VGIC_CTRL_INIT
194 request the initialization of the VGIC, no additional parameter in
195 kvm_device_attr.addr.
196 KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES
197 save all LPI pending bits into guest RAM pending tables.
198
199 The first kB of the pending table is not altered by this operation.
200 Errors:
201 -ENXIO: VGIC not properly configured as required prior to calling
202 this attribute
203 -ENODEV: no online VCPU
204 -ENOMEM: memory shortage when allocating vgic internal data
205 -EFAULT: Invalid guest ram access
206 -EBUSY: One or more VCPUS are running
207
208
209 KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO
210 Attributes:
211 The attr field of kvm_device_attr encodes the following values:
212 bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 |
213 values: | mpidr | info | vINTID |
214
215 The vINTID specifies which set of IRQs is reported on.
216
217 The info field specifies which information userspace wants to get or set
218 using this interface. Currently we support the following info values:
219
220 VGIC_LEVEL_INFO_LINE_LEVEL:
221 Get/Set the input level of the IRQ line for a set of 32 contiguously
222 numbered interrupts.
223 vINTID must be a multiple of 32.
224
225 kvm_device_attr.addr points to a __u32 value which will contain a
226 bitmap where a set bit means the interrupt level is asserted.
227
228 Bit[n] indicates the status for interrupt vINTID + n.
229
230 SGIs and any interrupt with a higher ID than the number of interrupts
231 supported, will be RAZ/WI. LPIs are always edge-triggered and are
232 therefore not supported by this interface.
233
234 PPIs are reported per VCPU as specified in the mpidr field, and SPIs are
235 reported with the same value regardless of the mpidr specified.
236
237 The mpidr field encodes the CPU ID based on the affinity information in the
238 architecture defined MPIDR, and the field is encoded as follows:
239 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
240 | Aff3 | Aff2 | Aff1 | Aff0 |
241 Errors:
242 -EINVAL: vINTID is not multiple of 32 or
243 info field is not VGIC_LEVEL_INFO_LINE_LEVEL