^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ==================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) ARM Virtual Generic Interrupt Controller v2 (VGIC)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ==================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Device types supported:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) - KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Only one VGIC instance may be instantiated through either this API or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) legacy KVM_CREATE_IRQCHIP API. The created VGIC will act as the VM interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) controller, requiring emulated user-space devices to inject interrupts to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) VGIC instead of directly to CPUs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) GICv3 implementations with hardware compatibility support allow creating a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) guest GICv2 through this interface. For information on creating a guest GICv3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) device and guest ITS devices, see arm-vgic-v3.txt. It is not possible to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) create both a GICv3 and GICv2 device on the same VM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) Groups:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) KVM_DEV_ARM_VGIC_GRP_ADDR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) Attributes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) Base address in the guest physical address space of the GIC distributor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) This address needs to be 4K aligned and the region covers 4 KByte.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) KVM_VGIC_V2_ADDR_TYPE_CPU (rw, 64-bit)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) Base address in the guest physical address space of the GIC virtual cpu
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) This address needs to be 4K aligned and the region covers 4 KByte.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) Errors:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) ======= =============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) -E2BIG Address outside of addressable IPA range
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) -EINVAL Incorrectly aligned address
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) -EEXIST Address already configured
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) -ENXIO The group or attribute is unknown/unsupported for this device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) or hardware support is missing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) -EFAULT Invalid user pointer for attr->addr.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) ======= =============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) KVM_DEV_ARM_VGIC_GRP_DIST_REGS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) Attributes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) The attr field of kvm_device_attr encodes two values::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) values: | reserved | vcpu_index | offset |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) All distributor regs are (rw, 32-bit)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) The offset is relative to the "Distributor base address" as defined in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) GICv2 specs. Getting or setting such a register has the same effect as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) reading or writing the register on the actual hardware from the cpu whose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) index is specified with the vcpu_index field. Note that most distributor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) fields are not banked, but return the same value regardless of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) vcpu_index used to access the register.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) GICD_IIDR.Revision is updated when the KVM implementation of an emulated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) GICv2 is changed in a way directly observable by the guest or userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) Userspace should read GICD_IIDR from KVM and write back the read value to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) confirm its expected behavior is aligned with the KVM implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Userspace should set GICD_IIDR before setting any other registers (both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) KVM_DEV_ARM_VGIC_GRP_DIST_REGS and KVM_DEV_ARM_VGIC_GRP_CPU_REGS) to ensure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) the expected behavior. Unless GICD_IIDR has been set from userspace, writes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) to the interrupt group registers (GICD_IGROUPR) are ignored.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) Errors:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) ======= =====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) -ENXIO Getting or setting this register is not yet supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) -EBUSY One or more VCPUs are running
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) -EINVAL Invalid vcpu_index supplied
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) ======= =====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) KVM_DEV_ARM_VGIC_GRP_CPU_REGS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) Attributes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) The attr field of kvm_device_attr encodes two values::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) values: | reserved | vcpu_index | offset |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) All CPU interface regs are (rw, 32-bit)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) The offset specifies the offset from the "CPU interface base address" as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) defined in the GICv2 specs. Getting or setting such a register has the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) same effect as reading or writing the register on the actual hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) The Active Priorities Registers APRn are implementation defined, so we set a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) fixed format for our implementation that fits with the model of a "GICv2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) implementation without the security extensions" which we present to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) guest. This interface always exposes four register APR[0-3] describing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) maximum possible 128 preemption levels. The semantics of the register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) indicate if any interrupts in a given preemption level are in the active
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) state by setting the corresponding bit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) Thus, preemption level X has one or more active interrupts if and only if:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) APRn[X mod 32] == 0b1, where n = X / 32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) Bits for undefined preemption levels are RAZ/WI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Note that this differs from a CPU's view of the APRs on hardware in which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) a GIC without the security extensions expose group 0 and group 1 active
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) priorities in separate register groups, whereas we show a combined view
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) similar to GICv2's GICH_APR.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) For historical reasons and to provide ABI compatibility with userspace we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) export the GICC_PMR register in the format of the GICH_VMCR.VMPriMask
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) field in the lower 5 bits of a word, meaning that userspace must always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) use the lower 5 bits to communicate with the KVM device and must shift the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) value left by 3 places to obtain the actual priority mask level.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Errors:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) ======= =====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) -ENXIO Getting or setting this register is not yet supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) -EBUSY One or more VCPUs are running
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) -EINVAL Invalid vcpu_index supplied
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) ======= =====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) KVM_DEV_ARM_VGIC_GRP_NR_IRQS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) Attributes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) A value describing the number of interrupts (SGI, PPI and SPI) for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) this GIC instance, ranging from 64 to 1024, in increments of 32.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) Errors:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) ======= =============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) -EINVAL Value set is out of the expected range
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) -EBUSY Value has already be set, or GIC has already been initialized
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) with default values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) ======= =============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) KVM_DEV_ARM_VGIC_GRP_CTRL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) Attributes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) KVM_DEV_ARM_VGIC_CTRL_INIT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) request the initialization of the VGIC or ITS, no additional parameter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) in kvm_device_attr.addr.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) Errors:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) ======= =========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) -ENXIO VGIC not properly configured as required prior to calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) this attribute
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) -ENODEV no online VCPU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) -ENOMEM memory shortage when allocating vgic internal data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) ======= =========================================================
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags