About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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


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

1	ARM Virtual Generic Interrupt Controller v2 (VGIC)
2	==================================================
3	
4	Device types supported:
5	  KVM_DEV_TYPE_ARM_VGIC_V2     ARM Generic Interrupt Controller v2.0
6	
7	Only one VGIC instance may be instantiated through either this API or the
8	legacy KVM_CREATE_IRQCHIP API.  The created VGIC will act as the VM interrupt
9	controller, requiring emulated user-space devices to inject interrupts to the
10	VGIC instead of directly to CPUs.
11	
12	GICv3 implementations with hardware compatibility support allow creating a
13	guest GICv2 through this interface.  For information on creating a guest GICv3
14	device and guest ITS devices, see arm-vgic-v3.txt.  It is not possible to
15	create both a GICv3 and GICv2 device on the same VM.
16	
17	
18	Groups:
19	  KVM_DEV_ARM_VGIC_GRP_ADDR
20	  Attributes:
21	    KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit)
22	      Base address in the guest physical address space of the GIC distributor
23	      register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
24	      This address needs to be 4K aligned and the region covers 4 KByte.
25	
26	    KVM_VGIC_V2_ADDR_TYPE_CPU (rw, 64-bit)
27	      Base address in the guest physical address space of the GIC virtual cpu
28	      interface 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.
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	  KVM_DEV_ARM_VGIC_GRP_DIST_REGS
39	  Attributes:
40	    The attr field of kvm_device_attr encodes two values:
41	    bits:     | 63   ....  40 | 39 ..  32  |  31   ....    0 |
42	    values:   |    reserved   | vcpu_index |      offset     |
43	
44	    All distributor regs are (rw, 32-bit)
45	
46	    The offset is relative to the "Distributor base address" as defined in the
47	    GICv2 specs.  Getting or setting such a register has the same effect as
48	    reading or writing the register on the actual hardware from the cpu whose
49	    index is specified with the vcpu_index field.  Note that most distributor
50	    fields are not banked, but return the same value regardless of the
51	    vcpu_index used to access the register.
52	  Limitations:
53	    - Priorities are not implemented, and registers are RAZ/WI
54	    - Currently only implemented for KVM_DEV_TYPE_ARM_VGIC_V2.
55	  Errors:
56	    -ENXIO: Getting or setting this register is not yet supported
57	    -EBUSY: One or more VCPUs are running
58	    -EINVAL: Invalid vcpu_index supplied
59	
60	  KVM_DEV_ARM_VGIC_GRP_CPU_REGS
61	  Attributes:
62	    The attr field of kvm_device_attr encodes two values:
63	    bits:     | 63   ....  40 | 39 ..  32  |  31   ....    0 |
64	    values:   |    reserved   | vcpu_index |      offset     |
65	
66	    All CPU interface regs are (rw, 32-bit)
67	
68	    The offset specifies the offset from the "CPU interface base address" as
69	    defined in the GICv2 specs.  Getting or setting such a register has the
70	    same effect as reading or writing the register on the actual hardware.
71	
72	    The Active Priorities Registers APRn are implementation defined, so we set a
73	    fixed format for our implementation that fits with the model of a "GICv2
74	    implementation without the security extensions" which we present to the
75	    guest.  This interface always exposes four register APR[0-3] describing the
76	    maximum possible 128 preemption levels.  The semantics of the register
77	    indicate if any interrupts in a given preemption level are in the active
78	    state by setting the corresponding bit.
79	
80	    Thus, preemption level X has one or more active interrupts if and only if:
81	
82	      APRn[X mod 32] == 0b1,  where n = X / 32
83	
84	    Bits for undefined preemption levels are RAZ/WI.
85	
86	    Note that this differs from a CPU's view of the APRs on hardware in which
87	    a GIC without the security extensions expose group 0 and group 1 active
88	    priorities in separate register groups, whereas we show a combined view
89	    similar to GICv2's GICH_APR.
90	
91	    For historical reasons and to provide ABI compatibility with userspace we
92	    export the GICC_PMR register in the format of the GICH_VMCR.VMPriMask
93	    field in the lower 5 bits of a word, meaning that userspace must always
94	    use the lower 5 bits to communicate with the KVM device and must shift the
95	    value left by 3 places to obtain the actual priority mask level.
96	
97	  Limitations:
98	    - Priorities are not implemented, and registers are RAZ/WI
99	    - Currently only implemented for KVM_DEV_TYPE_ARM_VGIC_V2.
100	  Errors:
101	    -ENXIO: Getting or setting this register is not yet supported
102	    -EBUSY: One or more VCPUs are running
103	    -EINVAL: Invalid vcpu_index supplied
104	
105	  KVM_DEV_ARM_VGIC_GRP_NR_IRQS
106	  Attributes:
107	    A value describing the number of interrupts (SGI, PPI and SPI) for
108	    this GIC instance, ranging from 64 to 1024, in increments of 32.
109	
110	  Errors:
111	    -EINVAL: Value set is out of the expected range
112	    -EBUSY: Value has already be set, or GIC has already been initialized
113	            with default values.
114	
115	  KVM_DEV_ARM_VGIC_GRP_CTRL
116	  Attributes:
117	    KVM_DEV_ARM_VGIC_CTRL_INIT
118	      request the initialization of the VGIC or ITS, no additional parameter
119	      in kvm_device_attr.addr.
120	  Errors:
121	    -ENXIO: VGIC not properly configured as required prior to calling
122	     this attribute
123	    -ENODEV: no online VCPU
124	    -ENOMEM: memory shortage when allocating vgic internal data
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog