About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / virtual / kvm / devices / arm-vgic-v3.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog