xref: /linux/Documentation/virt/kvm/devices/arm-vgic-v3.rst (revision 63eb28bb1402891b1ad2be02a530f29a9dd7f1cd)
1.. SPDX-License-Identifier: GPL-2.0
2
3==============================================================
4ARM Virtual Generic Interrupt Controller v3 and later (VGICv3)
5==============================================================
6
7
8Device types supported:
9  - KVM_DEV_TYPE_ARM_VGIC_V3     ARM Generic Interrupt Controller v3.0
10
11Only one VGIC instance may be instantiated through this API.  The created VGIC
12will act as the VM interrupt controller, requiring emulated user-space devices
13to inject interrupts to the VGIC instead of directly to CPUs.  It is not
14possible to create both a GICv3 and GICv2 on the same VM.
15
16Creating a guest GICv3 device requires a host GICv3 as well.
17
18
19Groups:
20  KVM_DEV_ARM_VGIC_GRP_ADDR
21   Attributes:
22
23    KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit)
24      Base address in the guest physical address space of the GICv3 distributor
25      register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
26      This address needs to be 64K aligned and the region covers 64 KByte.
27
28    KVM_VGIC_V3_ADDR_TYPE_REDIST (rw, 64-bit)
29      Base address in the guest physical address space of the GICv3
30      redistributor register mappings. There are two 64K pages for each
31      VCPU and all of the redistributor pages are contiguous.
32      Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
33      This address needs to be 64K aligned.
34
35    KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION (rw, 64-bit)
36      The attribute data pointed to by kvm_device_attr.addr is a __u64 value::
37
38        bits:     | 63   ....  52  |  51   ....   16 | 15 - 12  |11 - 0
39        values:   |     count      |       base      |  flags   | index
40
41      - index encodes the unique redistributor region index
42      - flags: reserved for future use, currently 0
43      - base field encodes bits [51:16] of the guest physical base address
44        of the first redistributor in the region.
45      - count encodes the number of redistributors in the region. Must be
46        greater than 0.
47
48      There are two 64K pages for each redistributor in the region and
49      redistributors are laid out contiguously within the region. Regions
50      are filled with redistributors in the index order. The sum of all
51      region count fields must be greater than or equal to the number of
52      VCPUs. Redistributor regions must be registered in the incremental
53      index order, starting from index 0.
54
55      The characteristics of a specific redistributor region can be read
56      by presetting the index field in the attr data.
57      Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
58
59  It is invalid to mix calls with KVM_VGIC_V3_ADDR_TYPE_REDIST and
60  KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes.
61
62  Note that to obtain reproducible results (the same VCPU being associated
63  with the same redistributor across a save/restore operation), VCPU creation
64  order, redistributor region creation order as well as the respective
65  interleaves of VCPU and region creation MUST be preserved.  Any change in
66  either ordering may result in a different vcpu_id/redistributor association,
67  resulting in a VM that will fail to run at restore time.
68
69  Errors:
70
71    =======  =============================================================
72    -E2BIG   Address outside of addressable IPA range
73    -EINVAL  Incorrectly aligned address, bad redistributor region
74             count/index, mixed redistributor region attribute usage
75    -EEXIST  Address already configured
76    -ENOENT  Attempt to read the characteristics of a non existing
77             redistributor region
78    -ENXIO   The group or attribute is unknown/unsupported for this device
79             or hardware support is missing.
80    -EFAULT  Invalid user pointer for attr->addr.
81    -EBUSY   Attempt to write a register that is read-only after
82             initialization
83    =======  =============================================================
84
85
86  KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS
87   Attributes:
88
89    The attr field of kvm_device_attr encodes two values::
90
91      bits:     | 63   ....  32  |  31   ....    0 |
92      values:   |      mpidr     |      offset     |
93
94    All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a
95    __u32 value.  64-bit registers must be accessed by separately accessing the
96    lower and higher word.
97
98    Writes to read-only registers are ignored by the kernel.
99
100    KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers.
101    KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU
102    specified by the mpidr.
103
104    The offset is relative to the "[Re]Distributor base address" as defined
105    in the GICv3/4 specs.  Getting or setting such a register has the same
106    effect as reading or writing the register on real hardware, except for the
107    following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR,
108    GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0.  These registers behave
109    differently when accessed via this interface compared to their
110    architecturally defined behavior to allow software a full view of the
111    VGIC's internal state.
112
113    The mpidr field is used to specify which
114    redistributor is accessed.  The mpidr is ignored for the distributor.
115
116    The mpidr encoding is based on the affinity information in the
117    architecture defined MPIDR, and the field is encoded as follows::
118
119      | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
120      |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
121
122    Note that distributor fields are not banked, but return the same value
123    regardless of the mpidr used to access the register.
124
125    Userspace is allowed to write the following register fields prior to
126    initialization of the VGIC:
127
128      * GICD_IIDR.Revision
129      * GICD_TYPER2.nASSGIcap
130
131    GICD_IIDR.Revision is updated when the KVM implementation is changed in a
132    way directly observable by the guest or userspace.  Userspace should read
133    GICD_IIDR from KVM and write back the read value to confirm its expected
134    behavior is aligned with the KVM implementation.  Userspace should set
135    GICD_IIDR before setting any other registers to ensure the expected
136    behavior.
137
138
139    GICD_TYPER2.nASSGIcap allows userspace to control the support of SGIs
140    without an active state. At VGIC creation the field resets to the
141    maximum capability of the system. Userspace is expected to read the field
142    to determine the supported value(s) before writing to the field.
143
144
145    The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such
146    that a write of a clear bit has no effect, whereas a write with a set bit
147    clears that value.  To allow userspace to freely set the values of these two
148    registers, setting the attributes with the register offsets for these two
149    registers simply sets the non-reserved bits to the value written.
150
151
152    Accesses (reads and writes) to the GICD_ISPENDR register region and
153    GICR_ISPENDR0 registers get/set the value of the latched pending state for
154    the interrupts.
155
156    This is identical to the value returned by a guest read from ISPENDR for an
157    edge triggered interrupt, but may differ for level triggered interrupts.
158    For edge triggered interrupts, once an interrupt becomes pending (whether
159    because of an edge detected on the input line or because of a guest write
160    to ISPENDR) this state is "latched", and only cleared when either the
161    interrupt is activated or when the guest writes to ICPENDR. A level
162    triggered interrupt may be pending either because the level input is held
163    high by a device, or because of a guest write to the ISPENDR register. Only
164    ISPENDR writes are latched; if the device lowers the line level then the
165    interrupt is no longer pending unless the guest also wrote to ISPENDR, and
166    conversely writes to ICPENDR or activations of the interrupt do not clear
167    the pending status if the line level is still being held high.  (These
168    rules are documented in the GICv3 specification descriptions of the ICPENDR
169    and ISPENDR registers.) For a level triggered interrupt the value accessed
170    here is that of the latch which is set by ISPENDR and cleared by ICPENDR or
171    interrupt activation, whereas the value returned by a guest read from
172    ISPENDR is the logical OR of the latch value and the input line level.
173
174    Raw access to the latch state is provided to userspace so that it can save
175    and restore the entire GIC internal state (which is defined by the
176    combination of the current input line level and the latch state, and cannot
177    be deduced from purely the line level and the value of the ISPENDR
178    registers).
179
180    Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have
181    RAZ/WI semantics, meaning that reads always return 0 and writes are always
182    ignored.
183
184  Errors:
185
186    ======  =====================================================
187    -ENXIO  Getting or setting this register is not yet supported
188    -EBUSY  One or more VCPUs are running
189    ======  =====================================================
190
191
192  KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS
193   Attributes:
194
195    The attr field of kvm_device_attr encodes two values::
196
197      bits:     | 63      ....       32 | 31  ....  16 | 15  ....  0 |
198      values:   |         mpidr         |      RES     |    instr    |
199
200    The mpidr field encodes the CPU ID based on the affinity information in the
201    architecture defined MPIDR, and the field is encoded as follows::
202
203      | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
204      |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
205
206    The instr field encodes the system register to access based on the fields
207    defined in the A64 instruction set encoding for system register access
208    (RES means the bits are reserved for future use and should be zero)::
209
210      | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 |
211      |   Op 0    |    Op1    |    CRn   |   CRm   |   Op2   |
212
213    All system regs accessed through this API are (rw, 64-bit) and
214    kvm_device_attr.addr points to a __u64 value.
215
216    KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the
217    CPU specified by the mpidr field.
218
219    The available registers are:
220
221    ===============  ====================================================
222    ICC_PMR_EL1
223    ICC_BPR0_EL1
224    ICC_AP0R0_EL1
225    ICC_AP0R1_EL1    when the host implements at least 6 bits of priority
226    ICC_AP0R2_EL1    when the host implements 7 bits of priority
227    ICC_AP0R3_EL1    when the host implements 7 bits of priority
228    ICC_AP1R0_EL1
229    ICC_AP1R1_EL1    when the host implements at least 6 bits of priority
230    ICC_AP1R2_EL1    when the host implements 7 bits of priority
231    ICC_AP1R3_EL1    when the host implements 7 bits of priority
232    ICC_BPR1_EL1
233    ICC_CTLR_EL1
234    ICC_SRE_EL1
235    ICC_IGRPEN0_EL1
236    ICC_IGRPEN1_EL1
237    ===============  ====================================================
238
239    When EL2 is available for the guest, these registers are also available:
240
241    =============  ====================================================
242    ICH_AP0R0_EL2
243    ICH_AP0R1_EL2  when the host implements at least 6 bits of priority
244    ICH_AP0R2_EL2  when the host implements 7 bits of priority
245    ICH_AP0R3_EL2  when the host implements 7 bits of priority
246    ICH_AP1R0_EL2
247    ICH_AP1R1_EL2  when the host implements at least 6 bits of priority
248    ICH_AP1R2_EL2  when the host implements 7 bits of priority
249    ICH_AP1R3_EL2  when the host implements 7 bits of priority
250    ICH_HCR_EL2
251    ICC_SRE_EL2
252    ICH_VTR_EL2
253    ICH_VMCR_EL2
254    ICH_LR0_EL2
255    ICH_LR1_EL2
256    ICH_LR2_EL2
257    ICH_LR3_EL2
258    ICH_LR4_EL2
259    ICH_LR5_EL2
260    ICH_LR6_EL2
261    ICH_LR7_EL2
262    ICH_LR8_EL2
263    ICH_LR9_EL2
264    ICH_LR10_EL2
265    ICH_LR11_EL2
266    ICH_LR12_EL2
267    ICH_LR13_EL2
268    ICH_LR14_EL2
269    ICH_LR15_EL2
270    =============  ====================================================
271
272    CPU interface registers are only described using the AArch64
273    encoding.
274
275  Errors:
276
277    =======  =================================================
278    -ENXIO   Getting or setting this register is not supported
279    -EBUSY   VCPU is running
280    -EINVAL  Invalid mpidr or register value supplied
281    =======  =================================================
282
283
284  KVM_DEV_ARM_VGIC_GRP_NR_IRQS
285   Attributes:
286
287    A value describing the number of interrupts (SGI, PPI and SPI) for
288    this GIC instance, ranging from 64 to 1024, in increments of 32.
289
290    kvm_device_attr.addr points to a __u32 value.
291
292  Errors:
293
294    =======  ======================================
295    -EINVAL  Value set is out of the expected range
296    -EBUSY   Value has already be set.
297    =======  ======================================
298
299
300  KVM_DEV_ARM_VGIC_GRP_CTRL
301   Attributes:
302
303    KVM_DEV_ARM_VGIC_CTRL_INIT
304      request the initialization of the VGIC, no additional parameter in
305      kvm_device_attr.addr. Must be called after all VCPUs have been created.
306    KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES
307      save all LPI pending bits into guest RAM pending tables.
308
309      The first kB of the pending table is not altered by this operation.
310
311  Errors:
312
313    =======  ========================================================
314    -ENXIO   VGIC not properly configured as required prior to calling
315             this attribute
316    -ENODEV  no online VCPU
317    -ENOMEM  memory shortage when allocating vgic internal data
318    -EFAULT  Invalid guest ram access
319    -EBUSY   One or more VCPUS are running
320    =======  ========================================================
321
322
323  KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO
324   Attributes:
325
326    The attr field of kvm_device_attr encodes the following values::
327
328      bits:     | 63      ....       32 | 31   ....    10 | 9  ....  0 |
329      values:   |         mpidr         |      info       |   vINTID   |
330
331    The vINTID specifies which set of IRQs is reported on.
332
333    The info field specifies which information userspace wants to get or set
334    using this interface.  Currently we support the following info values:
335
336      VGIC_LEVEL_INFO_LINE_LEVEL:
337	Get/Set the input level of the IRQ line for a set of 32 contiguously
338	numbered interrupts.
339
340	vINTID must be a multiple of 32.
341
342	kvm_device_attr.addr points to a __u32 value which will contain a
343	bitmap where a set bit means the interrupt level is asserted.
344
345	Bit[n] indicates the status for interrupt vINTID + n.
346
347    SGIs and any interrupt with a higher ID than the number of interrupts
348    supported, will be RAZ/WI.  LPIs are always edge-triggered and are
349    therefore not supported by this interface.
350
351    PPIs are reported per VCPU as specified in the mpidr field, and SPIs are
352    reported with the same value regardless of the mpidr specified.
353
354    The mpidr field encodes the CPU ID based on the affinity information in the
355    architecture defined MPIDR, and the field is encoded as follows::
356
357      | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
358      |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
359
360  Errors:
361    =======  =============================================
362    -EINVAL  vINTID is not multiple of 32 or info field is
363	     not VGIC_LEVEL_INFO_LINE_LEVEL
364    =======  =============================================
365
366  KVM_DEV_ARM_VGIC_GRP_MAINT_IRQ
367   Attributes:
368
369    The attr field of kvm_device_attr encodes the following values:
370
371      bits:     | 31   ....    5 | 4  ....  0 |
372      values:   |      RES0      |   vINTID   |
373
374    The vINTID specifies which interrupt is generated when the vGIC
375    must generate a maintenance interrupt. This must be a PPI.
376