268 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3======================4Generic vcpu interface5======================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 struct9kvm_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_CTRL14==================================15 16:Architectures: ARM6417 181.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ19---------------------------------------20 21:Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a22 pointer to an int23 24Returns:25 26 ======= ========================================================27 -EBUSY The PMU overflow interrupt is already set28 -EFAULT Error reading interrupt number29 -ENXIO PMUv3 not supported or the overflow interrupt not set30 when attempting to get it31 -ENODEV KVM_ARM_VCPU_PMU_V3 feature missing from VCPU32 -EINVAL Invalid PMU overflow interrupt number supplied or33 trying to set the IRQ number without using an in-kernel34 irqchip.35 ======= ========================================================36 37A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt38number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt39type must be same for each vcpu. As a PPI, the interrupt number is the same for40all vcpus, while as an SPI it must be a separate number per vcpu.41 421.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT43---------------------------------------44 45:Parameters: no additional parameter in kvm_device_attr.addr46 47Returns:48 49 ======= ======================================================50 -EEXIST Interrupt number already used51 -ENODEV PMUv3 not supported or GIC not initialized52 -ENXIO PMUv3 not supported, missing VCPU feature or interrupt53 number not set54 -EBUSY PMUv3 already initialized55 ======= ======================================================56 57Request the initialization of the PMUv3. If using the PMUv3 with an in-kernel58virtual GIC implementation, this must be done after initializing the in-kernel59irqchip.60 611.3 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_FILTER62-----------------------------------------63 64:Parameters: in kvm_device_attr.addr the address for a PMU event filter is a65 pointer to a struct kvm_pmu_event_filter66 67:Returns:68 69 ======= ======================================================70 -ENODEV PMUv3 not supported or GIC not initialized71 -ENXIO PMUv3 not properly configured or in-kernel irqchip not72 configured as required prior to calling this attribute73 -EBUSY PMUv3 already initialized or a VCPU has already run74 -EINVAL Invalid filter range75 ======= ======================================================76 77Request the installation of a PMU event filter described as follows::78 79 struct kvm_pmu_event_filter {80 __u16 base_event;81 __u16 nevents;82 83 #define KVM_PMU_EVENT_ALLOW 084 #define KVM_PMU_EVENT_DENY 185 86 __u8 action;87 __u8 pad[3];88 };89 90A filter range is defined as the range [@base_event, @base_event + @nevents),91together with an @action (KVM_PMU_EVENT_ALLOW or KVM_PMU_EVENT_DENY). The92first registered range defines the global policy (global ALLOW if the first93@action is DENY, global DENY if the first @action is ALLOW). Multiple ranges94can be programmed, and must fit within the event space defined by the PMU95architecture (10 bits on ARMv8.0, 16 bits from ARMv8.1 onwards).96 97Note: "Cancelling" a filter by registering the opposite action for the same98range doesn't change the default action. For example, installing an ALLOW99filter for event range [0:10) as the first filter and then applying a DENY100action for the same range will leave the whole range as disabled.101 102Restrictions: Event 0 (SW_INCR) is never filtered, as it doesn't count a103hardware event. Filtering event 0x1E (CHAIN) has no effect either, as it104isn't strictly speaking an event. Filtering the cycle counter is possible105using event 0x11 (CPU_CYCLES).106 1071.4 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_SET_PMU108------------------------------------------109 110:Parameters: in kvm_device_attr.addr the address to an int representing the PMU111 identifier.112 113:Returns:114 115 ======= ====================================================116 -EBUSY PMUv3 already initialized, a VCPU has already run or117 an event filter has already been set118 -EFAULT Error accessing the PMU identifier119 -ENXIO PMU not found120 -ENODEV PMUv3 not supported or GIC not initialized121 -ENOMEM Could not allocate memory122 ======= ====================================================123 124Request that the VCPU uses the specified hardware PMU when creating guest events125for the purpose of PMU emulation. The PMU identifier can be read from the "type"126file for the desired PMU instance under /sys/devices (or, equivalent,127/sys/bus/even_source). This attribute is particularly useful on heterogeneous128systems where there are at least two CPU PMUs on the system. The PMU that is set129for one VCPU will be used by all the other VCPUs. It isn't possible to set a PMU130if a PMU event filter is already present.131 132Note that KVM will not make any attempts to run the VCPU on the physical CPUs133associated with the PMU specified by this attribute. This is entirely left to134userspace. However, attempting to run the VCPU on a physical CPU not supported135by the PMU will fail and KVM_RUN will return with136exit_reason = KVM_EXIT_FAIL_ENTRY and populate the fail_entry struct by setting137hardare_entry_failure_reason field to KVM_EXIT_FAIL_ENTRY_CPU_UNSUPPORTED and138the cpu field to the processor id.139 1402. GROUP: KVM_ARM_VCPU_TIMER_CTRL141=================================142 143:Architectures: ARM64144 1452.1. ATTRIBUTES: KVM_ARM_VCPU_TIMER_IRQ_VTIMER, KVM_ARM_VCPU_TIMER_IRQ_PTIMER146-----------------------------------------------------------------------------147 148:Parameters: in kvm_device_attr.addr the address for the timer interrupt is a149 pointer to an int150 151Returns:152 153 ======= =================================154 -EINVAL Invalid timer interrupt number155 -EBUSY One or more VCPUs has already run156 ======= =================================157 158A value describing the architected timer interrupt number when connected to an159in-kernel virtual GIC. These must be a PPI (16 <= intid < 32). Setting the160attribute overrides the default values (see below).161 162============================= ==========================================163KVM_ARM_VCPU_TIMER_IRQ_VTIMER The EL1 virtual timer intid (default: 27)164KVM_ARM_VCPU_TIMER_IRQ_PTIMER The EL1 physical timer intid (default: 30)165============================= ==========================================166 167Setting the same PPI for different timers will prevent the VCPUs from running.168Setting the interrupt number on a VCPU configures all VCPUs created at that169time to use the number provided for a given timer, overwriting any previously170configured values on other VCPUs. Userspace should configure the interrupt171numbers on at least one VCPU after creating all VCPUs and before running any172VCPUs.173 174.. _kvm_arm_vcpu_pvtime_ctrl:175 1763. GROUP: KVM_ARM_VCPU_PVTIME_CTRL177==================================178 179:Architectures: ARM64180 1813.1 ATTRIBUTE: KVM_ARM_VCPU_PVTIME_IPA182--------------------------------------183 184:Parameters: 64-bit base address185 186Returns:187 188 ======= ======================================189 -ENXIO Stolen time not implemented190 -EEXIST Base address already set for this VCPU191 -EINVAL Base address not 64 byte aligned192 ======= ======================================193 194Specifies the base address of the stolen time structure for this VCPU. The195base address must be 64 byte aligned and exist within a valid guest memory196region. See Documentation/virt/kvm/arm/pvtime.rst for more information197including the layout of the stolen time structure.198 1994. GROUP: KVM_VCPU_TSC_CTRL200===========================201 202:Architectures: x86203 2044.1 ATTRIBUTE: KVM_VCPU_TSC_OFFSET205 206:Parameters: 64-bit unsigned TSC offset207 208Returns:209 210 ======= ======================================211 -EFAULT Error reading/writing the provided212 parameter address.213 -ENXIO Attribute not supported214 ======= ======================================215 216Specifies the guest's TSC offset relative to the host's TSC. The guest's217TSC is then derived by the following equation:218 219 guest_tsc = host_tsc + KVM_VCPU_TSC_OFFSET220 221This attribute is useful to adjust the guest's TSC on live migration,222so that the TSC counts the time during which the VM was paused. The223following describes a possible algorithm to use for this purpose.224 225From the source VMM process:226 2271. Invoke the KVM_GET_CLOCK ioctl to record the host TSC (tsc_src),228 kvmclock nanoseconds (guest_src), and host CLOCK_REALTIME nanoseconds229 (host_src).230 2312. Read the KVM_VCPU_TSC_OFFSET attribute for every vCPU to record the232 guest TSC offset (ofs_src[i]).233 2343. Invoke the KVM_GET_TSC_KHZ ioctl to record the frequency of the235 guest's TSC (freq).236 237From the destination VMM process:238 2394. Invoke the KVM_SET_CLOCK ioctl, providing the source nanoseconds from240 kvmclock (guest_src) and CLOCK_REALTIME (host_src) in their respective241 fields. Ensure that the KVM_CLOCK_REALTIME flag is set in the provided242 structure.243 244 KVM will advance the VM's kvmclock to account for elapsed time since245 recording the clock values. Note that this will cause problems in246 the guest (e.g., timeouts) unless CLOCK_REALTIME is synchronized247 between the source and destination, and a reasonably short time passes248 between the source pausing the VMs and the destination executing249 steps 4-7.250 2515. Invoke the KVM_GET_CLOCK ioctl to record the host TSC (tsc_dest) and252 kvmclock nanoseconds (guest_dest).253 2546. Adjust the guest TSC offsets for every vCPU to account for (1) time255 elapsed since recording state and (2) difference in TSCs between the256 source and destination machine:257 258 ofs_dst[i] = ofs_src[i] -259 (guest_src - guest_dest) * freq +260 (tsc_src - tsc_dest)261 262 ("ofs[i] + tsc - guest * freq" is the guest TSC value corresponding to263 a time of 0 in kvmclock. The above formula ensures that it is the264 same on the destination as it was on the source).265 2667. Write the KVM_VCPU_TSC_OFFSET attribute for every vCPU with the267 respective value derived in the previous step.268