1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 Clocks and Timers 3 Clocks and Timers
4 ================= 4 =================
5 5
6 arm64 6 arm64
7 ----- 7 -----
8 On arm64, Hyper-V virtualizes the ARMv8 archit 8 On arm64, Hyper-V virtualizes the ARMv8 architectural system counter
9 and timer. Guest VMs use this virtualized hard 9 and timer. Guest VMs use this virtualized hardware as the Linux
10 clocksource and clockevents via the standard a 10 clocksource and clockevents via the standard arm_arch_timer.c
11 driver, just as they would on bare metal. Linu 11 driver, just as they would on bare metal. Linux vDSO support for the
12 architectural system counter is functional in 12 architectural system counter is functional in guest VMs on Hyper-V.
13 While Hyper-V also provides a synthetic system 13 While Hyper-V also provides a synthetic system clock and four synthetic
14 per-CPU timers as described in the TLFS, they 14 per-CPU timers as described in the TLFS, they are not used by the
15 Linux kernel in a Hyper-V guest on arm64. How 15 Linux kernel in a Hyper-V guest on arm64. However, older versions
16 of Hyper-V for arm64 only partially virtualize 16 of Hyper-V for arm64 only partially virtualize the ARMv8
17 architectural timer, such that the timer does 17 architectural timer, such that the timer does not generate
18 interrupts in the VM. Because of this limitati 18 interrupts in the VM. Because of this limitation, running current
19 Linux kernel versions on these older Hyper-V v 19 Linux kernel versions on these older Hyper-V versions requires an
20 out-of-tree patch to use the Hyper-V synthetic 20 out-of-tree patch to use the Hyper-V synthetic clocks/timers instead.
21 21
22 x86/x64 22 x86/x64
23 ------- 23 -------
24 On x86/x64, Hyper-V provides guest VMs with a 24 On x86/x64, Hyper-V provides guest VMs with a synthetic system clock
25 and four synthetic per-CPU timers as described 25 and four synthetic per-CPU timers as described in the TLFS. Hyper-V
26 also provides access to the virtualized TSC vi 26 also provides access to the virtualized TSC via the RDTSC and
27 related instructions. These TSC instructions d 27 related instructions. These TSC instructions do not trap to
28 the hypervisor and so provide excellent perfor 28 the hypervisor and so provide excellent performance in a VM.
29 Hyper-V performs TSC calibration, and provides 29 Hyper-V performs TSC calibration, and provides the TSC frequency
30 to the guest VM via a synthetic MSR. Hyper-V 30 to the guest VM via a synthetic MSR. Hyper-V initialization code
31 in Linux reads this MSR to get the frequency, 31 in Linux reads this MSR to get the frequency, so it skips TSC
32 calibration and sets tsc_reliable. Hyper-V pro 32 calibration and sets tsc_reliable. Hyper-V provides virtualized
33 versions of the PIT (in Hyper-V Generation 1 33 versions of the PIT (in Hyper-V Generation 1 VMs only), local
34 APIC timer, and RTC. Hyper-V does not provide 34 APIC timer, and RTC. Hyper-V does not provide a virtualized HPET in
35 guest VMs. 35 guest VMs.
36 36
37 The Hyper-V synthetic system clock can be read 37 The Hyper-V synthetic system clock can be read via a synthetic MSR,
38 but this access traps to the hypervisor. As a 38 but this access traps to the hypervisor. As a faster alternative,
39 the guest can configure a memory page to be sh 39 the guest can configure a memory page to be shared between the guest
40 and the hypervisor. Hyper-V populates this me 40 and the hypervisor. Hyper-V populates this memory page with a
41 64-bit scale value and offset value. To read t 41 64-bit scale value and offset value. To read the synthetic clock
42 value, the guest reads the TSC and then applie 42 value, the guest reads the TSC and then applies the scale and offset
43 as described in the Hyper-V TLFS. The resultin 43 as described in the Hyper-V TLFS. The resulting value advances
44 at a constant 10 MHz frequency. In the case of 44 at a constant 10 MHz frequency. In the case of a live migration
45 to a host with a different TSC frequency, Hype 45 to a host with a different TSC frequency, Hyper-V adjusts the
46 scale and offset values in the shared page so 46 scale and offset values in the shared page so that the 10 MHz
47 frequency is maintained. 47 frequency is maintained.
48 48
49 Starting with Windows Server 2022 Hyper-V, Hyp 49 Starting with Windows Server 2022 Hyper-V, Hyper-V uses hardware
50 support for TSC frequency scaling to enable li 50 support for TSC frequency scaling to enable live migration of VMs
51 across Hyper-V hosts where the TSC frequency m 51 across Hyper-V hosts where the TSC frequency may be different.
52 When a Linux guest detects that this Hyper-V f 52 When a Linux guest detects that this Hyper-V functionality is
53 available, it prefers to use Linux's standard 53 available, it prefers to use Linux's standard TSC-based clocksource.
54 Otherwise, it uses the clocksource for the Hyp 54 Otherwise, it uses the clocksource for the Hyper-V synthetic system
55 clock implemented via the shared page (identif 55 clock implemented via the shared page (identified as
56 "hyperv_clocksource_tsc_page"). 56 "hyperv_clocksource_tsc_page").
57 57
58 The Hyper-V synthetic system clock is availabl 58 The Hyper-V synthetic system clock is available to user space via
59 vDSO, and gettimeofday() and related system ca 59 vDSO, and gettimeofday() and related system calls can execute
60 entirely in user space. The vDSO is implement 60 entirely in user space. The vDSO is implemented by mapping the
61 shared page with scale and offset values into 61 shared page with scale and offset values into user space. User
62 space code performs the same algorithm of read 62 space code performs the same algorithm of reading the TSC and
63 applying the scale and offset to get the const 63 applying the scale and offset to get the constant 10 MHz clock.
64 64
65 Linux clockevents are based on Hyper-V synthet 65 Linux clockevents are based on Hyper-V synthetic timer 0 (stimer0).
66 While Hyper-V offers 4 synthetic timers for ea 66 While Hyper-V offers 4 synthetic timers for each CPU, Linux only uses
67 timer 0. In older versions of Hyper-V, an inte 67 timer 0. In older versions of Hyper-V, an interrupt from stimer0
68 results in a VMBus control message that is dem 68 results in a VMBus control message that is demultiplexed by
69 vmbus_isr() as described in the Documentation/ 69 vmbus_isr() as described in the Documentation/virt/hyperv/vmbus.rst
70 documentation. In newer versions of Hyper-V, s 70 documentation. In newer versions of Hyper-V, stimer0 interrupts can
71 be mapped to an architectural interrupt, which 71 be mapped to an architectural interrupt, which is referred to as
72 "Direct Mode". Linux prefers to use Direct Mod 72 "Direct Mode". Linux prefers to use Direct Mode when available. Since
73 x86/x64 doesn't support per-CPU interrupts, Di 73 x86/x64 doesn't support per-CPU interrupts, Direct Mode statically
74 allocates an x86 interrupt vector (HYPERV_STIM 74 allocates an x86 interrupt vector (HYPERV_STIMER0_VECTOR) across all CPUs
75 and explicitly codes it to call the stimer0 in 75 and explicitly codes it to call the stimer0 interrupt handler. Hence
76 interrupts from stimer0 are recorded on the "H 76 interrupts from stimer0 are recorded on the "HVS" line in /proc/interrupts
77 rather than being associated with a Linux IRQ. 77 rather than being associated with a Linux IRQ. Clockevents based on the
78 virtualized PIT and local APIC timer also work 78 virtualized PIT and local APIC timer also work, but Hyper-V stimer0
79 is preferred. 79 is preferred.
80 80
81 The driver for the Hyper-V synthetic system cl 81 The driver for the Hyper-V synthetic system clock and timers is
82 drivers/clocksource/hyperv_timer.c. 82 drivers/clocksource/hyperv_timer.c.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.