1.. SPDX-License-Identifier: GPL-2.0
2
3Clocks and Timers
4=================
5
6arm64
7-----
8On arm64, Hyper-V virtualizes the ARMv8 architectural system counter
9and timer. Guest VMs use this virtualized hardware as the Linux
10clocksource and clockevents via the standard arm_arch_timer.c
11driver, just as they would on bare metal. Linux vDSO support for the
12architectural system counter is functional in guest VMs on Hyper-V.
13While Hyper-V also provides a synthetic system clock and four synthetic
14per-CPU timers as described in the TLFS, they are not used by the
15Linux kernel in a Hyper-V guest on arm64.  However, older versions
16of Hyper-V for arm64 only partially virtualize the ARMv8
17architectural timer, such that the timer does not generate
18interrupts in the VM. Because of this limitation, running current
19Linux kernel versions on these older Hyper-V versions requires an
20out-of-tree patch to use the Hyper-V synthetic clocks/timers instead.
21
22x86/x64
23-------
24On x86/x64, Hyper-V provides guest VMs with a synthetic system clock
25and four synthetic per-CPU timers as described in the TLFS. Hyper-V
26also provides access to the virtualized TSC via the RDTSC and
27related instructions. These TSC instructions do not trap to
28the hypervisor and so provide excellent performance in a VM.
29Hyper-V performs TSC calibration, and provides the TSC frequency
30to the guest VM via a synthetic MSR.  Hyper-V initialization code
31in Linux reads this MSR to get the frequency, so it skips TSC
32calibration and sets tsc_reliable. Hyper-V provides virtualized
33versions of the PIT (in Hyper-V  Generation 1 VMs only), local
34APIC timer, and RTC. Hyper-V does not provide a virtualized HPET in
35guest VMs.
36
37The Hyper-V synthetic system clock can be read via a synthetic MSR,
38but this access traps to the hypervisor. As a faster alternative,
39the guest can configure a memory page to be shared between the guest
40and the hypervisor.  Hyper-V populates this memory page with a
4164-bit scale value and offset value. To read the synthetic clock
42value, the guest reads the TSC and then applies the scale and offset
43as described in the Hyper-V TLFS. The resulting value advances
44at a constant 10 MHz frequency. In the case of a live migration
45to a host with a different TSC frequency, Hyper-V adjusts the
46scale and offset values in the shared page so that the 10 MHz
47frequency is maintained.
48
49Starting with Windows Server 2022 Hyper-V, Hyper-V uses hardware
50support for TSC frequency scaling to enable live migration of VMs
51across Hyper-V hosts where the TSC frequency may be different.
52When a Linux guest detects that this Hyper-V functionality is
53available, it prefers to use Linux's standard TSC-based clocksource.
54Otherwise, it uses the clocksource for the Hyper-V synthetic system
55clock implemented via the shared page (identified as
56"hyperv_clocksource_tsc_page").
57
58The Hyper-V synthetic system clock is available to user space via
59vDSO, and gettimeofday() and related system calls can execute
60entirely in user space.  The vDSO is implemented by mapping the
61shared page with scale and offset values into user space.  User
62space code performs the same algorithm of reading the TSC and
63applying the scale and offset to get the constant 10 MHz clock.
64
65Linux clockevents are based on Hyper-V synthetic timer 0. While
66Hyper-V offers 4 synthetic timers for each CPU, Linux only uses
67timer 0. Interrupts from stimer0 are recorded on the "HVS" line in
68/proc/interrupts.  Clockevents based on the virtualized PIT and
69local APIC timer also work, but the Hyper-V synthetic timer is
70preferred.
71
72The driver for the Hyper-V synthetic system clock and timers is
73drivers/clocksource/hyperv_timer.c.
74