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 applying 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.