1.. SPDX-License-Identifier: GPL-2.0 2 3========================= 4XICS interrupt controller 5========================= 6 7Device type supported: KVM_DEV_TYPE_XICS 8 9Groups: 10 1. KVM_DEV_XICS_GRP_SOURCES 11 Attributes: 12 13 One per interrupt source, indexed by the source number. 14 2. KVM_DEV_XICS_GRP_CTRL 15 Attributes: 16 17 2.1 KVM_DEV_XICS_NR_SERVERS (write only) 18 19 The kvm_device_attr.addr points to a __u32 value which is the number of 20 interrupt server numbers (ie, highest possible vcpu id plus one). 21 22 Errors: 23 24 ======= ========================================== 25 -EINVAL Value greater than KVM_MAX_VCPU_IDS. 26 -EFAULT Invalid user pointer for attr->addr. 27 -EBUSY A vcpu is already connected to the device. 28 ======= ========================================== 29 30This device emulates the XICS (eXternal Interrupt Controller 31Specification) defined in PAPR. The XICS has a set of interrupt 32sources, each identified by a 20-bit source number, and a set of 33Interrupt Control Presentation (ICP) entities, also called "servers", 34each associated with a virtual CPU. 35 36The ICP entities are created by enabling the KVM_CAP_IRQ_ARCH 37capability for each vcpu, specifying KVM_CAP_IRQ_XICS in args[0] and 38the interrupt server number (i.e. the vcpu number from the XICS's 39point of view) in args[1] of the kvm_enable_cap struct. Each ICP has 4064 bits of state which can be read and written using the 41KVM_GET_ONE_REG and KVM_SET_ONE_REG ioctls on the vcpu. The 64 bit 42state word has the following bitfields, starting at the 43least-significant end of the word: 44 45* Unused, 16 bits 46 47* Pending interrupt priority, 8 bits 48 Zero is the highest priority, 255 means no interrupt is pending. 49 50* Pending IPI (inter-processor interrupt) priority, 8 bits 51 Zero is the highest priority, 255 means no IPI is pending. 52 53* Pending interrupt source number, 24 bits 54 Zero means no interrupt pending, 2 means an IPI is pending 55 56* Current processor priority, 8 bits 57 Zero is the highest priority, meaning no interrupts can be 58 delivered, and 255 is the lowest priority. 59 60Each source has 64 bits of state that can be read and written using 61the KVM_GET_DEVICE_ATTR and KVM_SET_DEVICE_ATTR ioctls, specifying the 62KVM_DEV_XICS_GRP_SOURCES attribute group, with the attribute number being 63the interrupt source number. The 64 bit state word has the following 64bitfields, starting from the least-significant end of the word: 65 66* Destination (server number), 32 bits 67 68 This specifies where the interrupt should be sent, and is the 69 interrupt server number specified for the destination vcpu. 70 71* Priority, 8 bits 72 73 This is the priority specified for this interrupt source, where 0 is 74 the highest priority and 255 is the lowest. An interrupt with a 75 priority of 255 will never be delivered. 76 77* Level sensitive flag, 1 bit 78 79 This bit is 1 for a level-sensitive interrupt source, or 0 for 80 edge-sensitive (or MSI). 81 82* Masked flag, 1 bit 83 84 This bit is set to 1 if the interrupt is masked (cannot be delivered 85 regardless of its priority), for example by the ibm,int-off RTAS 86 call, or 0 if it is not masked. 87 88* Pending flag, 1 bit 89 90 This bit is 1 if the source has a pending interrupt, otherwise 0. 91 92Only one XICS instance may be created per VM. 93