1.. SPDX-License-Identifier: GPL-2.0 2 3====================== 4Generic vcpu interface 5====================== 6 7The virtual cpu "device" also accepts the ioctls KVM_SET_DEVICE_ATTR, 8KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same struct 9kvm_device_attr as other devices, but targets VCPU-wide settings and controls. 10 11The groups and attributes per virtual cpu, if any, are architecture specific. 12 131. GROUP: KVM_ARM_VCPU_PMU_V3_CTRL 14================================== 15 16:Architectures: ARM64 17 181.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ 19--------------------------------------- 20 21:Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a 22 pointer to an int 23 24Returns: 25 26 ======= ======================================================== 27 -EBUSY The PMU overflow interrupt is already set 28 -EFAULT Error reading interrupt number 29 -ENXIO PMUv3 not supported or the overflow interrupt not set 30 when attempting to get it 31 -ENODEV KVM_ARM_VCPU_PMU_V3 feature missing from VCPU 32 -EINVAL Invalid PMU overflow interrupt number supplied or 33 trying to set the IRQ number without using an in-kernel 34 irqchip. 35 ======= ======================================================== 36 37A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt 38number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt 39type must be same for each vcpu. As a PPI, the interrupt number is the same for 40all vcpus, while as an SPI it must be a separate number per vcpu. For 41GICv5-based guests, the architected PPI (23) must be used. 42 431.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT 44--------------------------------------- 45 46:Parameters: no additional parameter in kvm_device_attr.addr 47 48Returns: 49 50 ======= ====================================================== 51 -EEXIST Interrupt number already used 52 -ENODEV PMUv3 not supported or GIC not initialized 53 -ENXIO PMUv3 not supported, missing VCPU feature or interrupt 54 number not set (non-GICv5 guests, only) 55 -EBUSY PMUv3 already initialized 56 ======= ====================================================== 57 58Request the initialization of the PMUv3. If using the PMUv3 with an in-kernel 59virtual GIC implementation, this must be done after initializing the in-kernel 60irqchip. 61 621.3 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_FILTER 63----------------------------------------- 64 65:Parameters: in kvm_device_attr.addr the address for a PMU event filter is a 66 pointer to a struct kvm_pmu_event_filter 67 68:Returns: 69 70 ======= ====================================================== 71 -ENODEV PMUv3 not supported or GIC not initialized 72 -ENXIO PMUv3 not properly configured or in-kernel irqchip not 73 configured as required prior to calling this attribute 74 -EBUSY PMUv3 already initialized or a VCPU has already run 75 -EINVAL Invalid filter range 76 ======= ====================================================== 77 78Request the installation of a PMU event filter described as follows:: 79 80 struct kvm_pmu_event_filter { 81 __u16 base_event; 82 __u16 nevents; 83 84 #define KVM_PMU_EVENT_ALLOW 0 85 #define KVM_PMU_EVENT_DENY 1 86 87 __u8 action; 88 __u8 pad[3]; 89 }; 90 91A filter range is defined as the range [@base_event, @base_event + @nevents), 92together with an @action (KVM_PMU_EVENT_ALLOW or KVM_PMU_EVENT_DENY). The 93first registered range defines the global policy (global ALLOW if the first 94@action is DENY, global DENY if the first @action is ALLOW). Multiple ranges 95can be programmed, and must fit within the event space defined by the PMU 96architecture (10 bits on ARMv8.0, 16 bits from ARMv8.1 onwards). 97 98Note: "Cancelling" a filter by registering the opposite action for the same 99range doesn't change the default action. For example, installing an ALLOW 100filter for event range [0:10) as the first filter and then applying a DENY 101action for the same range will leave the whole range as disabled. 102 103Restrictions: Event 0 (SW_INCR) is never filtered, as it doesn't count a 104hardware event. Filtering event 0x1E (CHAIN) has no effect either, as it 105isn't strictly speaking an event. Filtering the cycle counter is possible 106using event 0x11 (CPU_CYCLES). 107 1081.4 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_SET_PMU 109------------------------------------------ 110 111:Parameters: in kvm_device_attr.addr the address to an int representing the PMU 112 identifier. 113 114:Returns: 115 116 ======= ==================================================== 117 -EBUSY PMUv3 already initialized, a VCPU has already run or 118 an event filter has already been set 119 -EFAULT Error accessing the PMU identifier 120 -ENXIO PMU not found 121 -ENODEV PMUv3 not supported or GIC not initialized 122 -ENOMEM Could not allocate memory 123 ======= ==================================================== 124 125Request that the VCPU uses the specified hardware PMU when creating guest events 126for the purpose of PMU emulation. The PMU identifier can be read from the "type" 127file for the desired PMU instance under /sys/devices (or, equivalent, 128/sys/bus/even_source). This attribute is particularly useful on heterogeneous 129systems where there are at least two CPU PMUs on the system. The PMU that is set 130for one VCPU will be used by all the other VCPUs. It isn't possible to set a PMU 131if a PMU event filter is already present. 132 133Note that KVM will not make any attempts to run the VCPU on the physical CPUs 134associated with the PMU specified by this attribute. This is entirely left to 135userspace. However, attempting to run the VCPU on a physical CPU not supported 136by the PMU will fail and KVM_RUN will return with 137exit_reason = KVM_EXIT_FAIL_ENTRY and populate the fail_entry struct by setting 138hardare_entry_failure_reason field to KVM_EXIT_FAIL_ENTRY_CPU_UNSUPPORTED and 139the cpu field to the processor id. 140 1411.5 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_SET_NR_COUNTERS 142-------------------------------------------------- 143 144:Parameters: in kvm_device_attr.addr the address to an unsigned int 145 representing the maximum value taken by PMCR_EL0.N 146 147:Returns: 148 149 ======= ==================================================== 150 -EBUSY PMUv3 already initialized, a VCPU has already run or 151 an event filter has already been set 152 -EFAULT Error accessing the value pointed to by addr 153 -ENODEV PMUv3 not supported or GIC not initialized 154 -EINVAL No PMUv3 explicitly selected, or value of N out of 155 range 156 ======= ==================================================== 157 158Set the number of implemented event counters in the virtual PMU. This 159mandates that a PMU has explicitly been selected via 160KVM_ARM_VCPU_PMU_V3_SET_PMU, and will fail when no PMU has been 161explicitly selected, or the number of counters is out of range for the 162selected PMU. Selecting a new PMU cancels the effect of setting this 163attribute. 164 1652. GROUP: KVM_ARM_VCPU_TIMER_CTRL 166================================= 167 168:Architectures: ARM64 169 1702.1. ATTRIBUTES: KVM_ARM_VCPU_TIMER_IRQ_{VTIMER,PTIMER,HVTIMER,HPTIMER} 171----------------------------------------------------------------------- 172 173:Parameters: in kvm_device_attr.addr the address for the timer interrupt is a 174 pointer to an int 175 176Returns: 177 178 ======= ================================= 179 -EINVAL Invalid timer interrupt number 180 -EBUSY One or more VCPUs has already run 181 ======= ================================= 182 183A value describing the architected timer interrupt number when connected to an 184in-kernel virtual GIC. These must be a PPI (16 <= intid < 32). Setting the 185attribute overrides the default values (see below). 186 187============================== ========================================== 188KVM_ARM_VCPU_TIMER_IRQ_VTIMER The EL1 virtual timer intid (default: 27) 189KVM_ARM_VCPU_TIMER_IRQ_PTIMER The EL1 physical timer intid (default: 30) 190KVM_ARM_VCPU_TIMER_IRQ_HVTIMER The EL2 virtual timer intid (default: 28) 191KVM_ARM_VCPU_TIMER_IRQ_HPTIMER The EL2 physical timer intid (default: 26) 192============================== ========================================== 193 194Setting the same PPI for different timers will prevent the VCPUs from running. 195Setting the interrupt number on a VCPU configures all VCPUs created at that 196time to use the number provided for a given timer, overwriting any previously 197configured values on other VCPUs. Userspace should configure the interrupt 198numbers on at least one VCPU after creating all VCPUs and before running any 199VCPUs. 200 201.. _kvm_arm_vcpu_pvtime_ctrl: 202 2033. GROUP: KVM_ARM_VCPU_PVTIME_CTRL 204================================== 205 206:Architectures: ARM64 207 2083.1 ATTRIBUTE: KVM_ARM_VCPU_PVTIME_IPA 209-------------------------------------- 210 211:Parameters: 64-bit base address 212 213Returns: 214 215 ======= ====================================== 216 -ENXIO Stolen time not implemented 217 -EEXIST Base address already set for this VCPU 218 -EINVAL Base address not 64 byte aligned 219 ======= ====================================== 220 221Specifies the base address of the stolen time structure for this VCPU. The 222base address must be 64 byte aligned and exist within a valid guest memory 223region. See Documentation/virt/kvm/arm/pvtime.rst for more information 224including the layout of the stolen time structure. 225 2264. GROUP: KVM_VCPU_TSC_CTRL 227=========================== 228 229:Architectures: x86 230 2314.1 ATTRIBUTE: KVM_VCPU_TSC_OFFSET 232 233:Parameters: 64-bit unsigned TSC offset 234 235Returns: 236 237 ======= ====================================== 238 -EFAULT Error reading/writing the provided 239 parameter address. 240 -ENXIO Attribute not supported 241 ======= ====================================== 242 243Specifies the guest's TSC offset relative to the host's TSC. The guest's 244TSC is then derived by the following equation: 245 246 guest_tsc = host_tsc + KVM_VCPU_TSC_OFFSET 247 248This attribute is useful to adjust the guest's TSC on live migration, 249so that the TSC counts the time during which the VM was paused. The 250following describes a possible algorithm to use for this purpose. 251 252From the source VMM process: 253 2541. Invoke the KVM_GET_CLOCK ioctl to record the host TSC (tsc_src), 255 kvmclock nanoseconds (guest_src), and host CLOCK_REALTIME nanoseconds 256 (host_src). 257 2582. Read the KVM_VCPU_TSC_OFFSET attribute for every vCPU to record the 259 guest TSC offset (ofs_src[i]). 260 2613. Invoke the KVM_GET_TSC_KHZ ioctl to record the frequency of the 262 guest's TSC (freq). 263 264From the destination VMM process: 265 2664. Invoke the KVM_SET_CLOCK ioctl, providing the source nanoseconds from 267 kvmclock (guest_src) and CLOCK_REALTIME (host_src) in their respective 268 fields. Ensure that the KVM_CLOCK_REALTIME flag is set in the provided 269 structure. 270 271 KVM will advance the VM's kvmclock to account for elapsed time since 272 recording the clock values. Note that this will cause problems in 273 the guest (e.g., timeouts) unless CLOCK_REALTIME is synchronized 274 between the source and destination, and a reasonably short time passes 275 between the source pausing the VMs and the destination executing 276 steps 4-7. 277 2785. Invoke the KVM_GET_CLOCK ioctl to record the host TSC (tsc_dest) and 279 kvmclock nanoseconds (guest_dest). 280 2816. Adjust the guest TSC offsets for every vCPU to account for (1) time 282 elapsed since recording state and (2) difference in TSCs between the 283 source and destination machine: 284 285 ofs_dst[i] = ofs_src[i] - 286 (guest_src - guest_dest) * freq + 287 (tsc_src - tsc_dest) 288 289 ("ofs[i] + tsc - guest * freq" is the guest TSC value corresponding to 290 a time of 0 in kvmclock. The above formula ensures that it is the 291 same on the destination as it was on the source). 292 2937. Write the KVM_VCPU_TSC_OFFSET attribute for every vCPU with the 294 respective value derived in the previous step. 295