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    =======  =============================================================
82
83
84  KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS
85   Attributes:
86
87    The attr field of kvm_device_attr encodes two values::
88
89      bits:     | 63   ....  32  |  31   ....    0 |
90      values:   |      mpidr     |      offset     |
91
92    All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a
93    __u32 value.  64-bit registers must be accessed by separately accessing the
94    lower and higher word.
95
96    Writes to read-only registers are ignored by the kernel.
97
98    KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers.
99    KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU
100    specified by the mpidr.
101
102    The offset is relative to the "[Re]Distributor base address" as defined
103    in the GICv3/4 specs.  Getting or setting such a register has the same
104    effect as reading or writing the register on real hardware, except for the
105    following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR,
106    GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0.  These registers behave
107    differently when accessed via this interface compared to their
108    architecturally defined behavior to allow software a full view of the
109    VGIC's internal state.
110
111    The mpidr field is used to specify which
112    redistributor is accessed.  The mpidr is ignored for the distributor.
113
114    The mpidr encoding is based on the affinity information in the
115    architecture defined MPIDR, and the field is encoded as follows::
116
117      | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
118      |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
119
120    Note that distributor fields are not banked, but return the same value
121    regardless of the mpidr used to access the register.
122
123    GICD_IIDR.Revision is updated when the KVM implementation is changed in a
124    way directly observable by the guest or userspace.  Userspace should read
125    GICD_IIDR from KVM and write back the read value to confirm its expected
126    behavior is aligned with the KVM implementation.  Userspace should set
127    GICD_IIDR before setting any other registers to ensure the expected
128    behavior.
129
130
131    The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such
132    that a write of a clear bit has no effect, whereas a write with a set bit
133    clears that value.  To allow userspace to freely set the values of these two
134    registers, setting the attributes with the register offsets for these two
135    registers simply sets the non-reserved bits to the value written.
136
137
138    Accesses (reads and writes) to the GICD_ISPENDR register region and
139    GICR_ISPENDR0 registers get/set the value of the latched pending state for
140    the interrupts.
141
142    This is identical to the value returned by a guest read from ISPENDR for an
143    edge triggered interrupt, but may differ for level triggered interrupts.
144    For edge triggered interrupts, once an interrupt becomes pending (whether
145    because of an edge detected on the input line or because of a guest write
146    to ISPENDR) this state is "latched", and only cleared when either the
147    interrupt is activated or when the guest writes to ICPENDR. A level
148    triggered interrupt may be pending either because the level input is held
149    high by a device, or because of a guest write to the ISPENDR register. Only
150    ISPENDR writes are latched; if the device lowers the line level then the
151    interrupt is no longer pending unless the guest also wrote to ISPENDR, and
152    conversely writes to ICPENDR or activations of the interrupt do not clear
153    the pending status if the line level is still being held high.  (These
154    rules are documented in the GICv3 specification descriptions of the ICPENDR
155    and ISPENDR registers.) For a level triggered interrupt the value accessed
156    here is that of the latch which is set by ISPENDR and cleared by ICPENDR or
157    interrupt activation, whereas the value returned by a guest read from
158    ISPENDR is the logical OR of the latch value and the input line level.
159
160    Raw access to the latch state is provided to userspace so that it can save
161    and restore the entire GIC internal state (which is defined by the
162    combination of the current input line level and the latch state, and cannot
163    be deduced from purely the line level and the value of the ISPENDR
164    registers).
165
166    Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have
167    RAZ/WI semantics, meaning that reads always return 0 and writes are always
168    ignored.
169
170  Errors:
171
172    ======  =====================================================
173    -ENXIO  Getting or setting this register is not yet supported
174    -EBUSY  One or more VCPUs are running
175    ======  =====================================================
176
177
178  KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS
179   Attributes:
180
181    The attr field of kvm_device_attr encodes two values::
182
183      bits:     | 63      ....       32 | 31  ....  16 | 15  ....  0 |
184      values:   |         mpidr         |      RES     |    instr    |
185
186    The mpidr field encodes the CPU ID based on the affinity information in the
187    architecture defined MPIDR, and the field is encoded as follows::
188
189      | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
190      |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
191
192    The instr field encodes the system register to access based on the fields
193    defined in the A64 instruction set encoding for system register access
194    (RES means the bits are reserved for future use and should be zero)::
195
196      | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 |
197      |   Op 0    |    Op1    |    CRn   |   CRm   |   Op2   |
198
199    All system regs accessed through this API are (rw, 64-bit) and
200    kvm_device_attr.addr points to a __u64 value.
201
202    KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the
203    CPU specified by the mpidr field.
204
205    CPU interface registers access is not implemented for AArch32 mode.
206    Error -ENXIO is returned when accessed in AArch32 mode.
207
208  Errors:
209
210    =======  =====================================================
211    -ENXIO   Getting or setting this register is not yet supported
212    -EBUSY   VCPU is running
213    -EINVAL  Invalid mpidr or register value supplied
214    =======  =====================================================
215
216
217  KVM_DEV_ARM_VGIC_GRP_NR_IRQS
218   Attributes:
219
220    A value describing the number of interrupts (SGI, PPI and SPI) for
221    this GIC instance, ranging from 64 to 1024, in increments of 32.
222
223    kvm_device_attr.addr points to a __u32 value.
224
225  Errors:
226
227    =======  ======================================
228    -EINVAL  Value set is out of the expected range
229    -EBUSY   Value has already be set.
230    =======  ======================================
231
232
233  KVM_DEV_ARM_VGIC_GRP_CTRL
234   Attributes:
235
236    KVM_DEV_ARM_VGIC_CTRL_INIT
237      request the initialization of the VGIC, no additional parameter in
238      kvm_device_attr.addr. Must be called after all VCPUs have been created.
239    KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES
240      save all LPI pending bits into guest RAM pending tables.
241
242      The first kB of the pending table is not altered by this operation.
243
244  Errors:
245
246    =======  ========================================================
247    -ENXIO   VGIC not properly configured as required prior to calling
248             this attribute
249    -ENODEV  no online VCPU
250    -ENOMEM  memory shortage when allocating vgic internal data
251    -EFAULT  Invalid guest ram access
252    -EBUSY   One or more VCPUS are running
253    =======  ========================================================
254
255
256  KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO
257   Attributes:
258
259    The attr field of kvm_device_attr encodes the following values::
260
261      bits:     | 63      ....       32 | 31   ....    10 | 9  ....  0 |
262      values:   |         mpidr         |      info       |   vINTID   |
263
264    The vINTID specifies which set of IRQs is reported on.
265
266    The info field specifies which information userspace wants to get or set
267    using this interface.  Currently we support the following info values:
268
269      VGIC_LEVEL_INFO_LINE_LEVEL:
270	Get/Set the input level of the IRQ line for a set of 32 contiguously
271	numbered interrupts.
272
273	vINTID must be a multiple of 32.
274
275	kvm_device_attr.addr points to a __u32 value which will contain a
276	bitmap where a set bit means the interrupt level is asserted.
277
278	Bit[n] indicates the status for interrupt vINTID + n.
279
280    SGIs and any interrupt with a higher ID than the number of interrupts
281    supported, will be RAZ/WI.  LPIs are always edge-triggered and are
282    therefore not supported by this interface.
283
284    PPIs are reported per VCPU as specified in the mpidr field, and SPIs are
285    reported with the same value regardless of the mpidr specified.
286
287    The mpidr field encodes the CPU ID based on the affinity information in the
288    architecture defined MPIDR, and the field is encoded as follows::
289
290      | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
291      |    Aff3    |    Aff2    |    Aff1    |    Aff0    |
292
293  Errors:
294
295    =======  =============================================
296    -EINVAL  vINTID is not multiple of 32 or info field is
297	     not VGIC_LEVEL_INFO_LINE_LEVEL
298    =======  =============================================
299