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