Add documentation topic for clocks and timers when running as a
guest on Hyper-V.
Signed-off-by: Michael Kelley <[email protected]>
---
Documentation/virt/hyperv/clocks.rst | 73 ++++++++++++++++++++++++++++++++++++
Documentation/virt/hyperv/index.rst | 1 +
2 files changed, 74 insertions(+)
create mode 100644 Documentation/virt/hyperv/clocks.rst
diff --git a/Documentation/virt/hyperv/clocks.rst b/Documentation/virt/hyperv/clocks.rst
new file mode 100644
index 0000000..e4ba2890
--- /dev/null
+++ b/Documentation/virt/hyperv/clocks.rst
@@ -0,0 +1,73 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Clocks and Timers
+-----------------
+
+arm64
+~~~~~
+On arm64, Hyper-V virtualizes the ARMv8 architectural system counter
+and timer. Guest VMs use this virtualized hardware as the Linux
+clocksource and clockevents via the standard arm_arch_timer.c
+driver, just as they would on bare metal. Linux vDSO support for the
+architectural system counter is functional in guest VMs on Hyper-V.
+While Hyper-V also provides a synthetic system clock and four synthetic
+per-CPU timers as described in the TLFS, they are not used by the
+Linux kernel in a Hyper-V guest on arm64. However, older versions
+of Hyper-V for arm64 only partially virtualize the ARMv8
+architectural timer, such that the timer does not generate
+interrupts in the VM. Because of this limitation, running current
+Linux kernel versions on these older Hyper-V versions requires an
+out-of-tree patch to use the Hyper-V synthetic clocks/timers instead.
+
+x86/x64
+~~~~~~~
+On x86/x64, Hyper-V provides guest VMs with a synthetic system clock
+and four synthetic per-CPU timers as described in the TLFS. Hyper-V
+also provides access to the virtualized TSC via the RDTSC and
+related instructions. These TSC instructions do not trap to
+the hypervisor and so provide excellent performance in a VM.
+Hyper-V performs TSC calibration, and provides the TSC frequency
+to the guest VM via a synthetic MSR. Hyper-V initialization code
+in Linux reads this MSR to get the frequency, so it skips TSC
+calibration and sets tsc_reliable. Hyper-V provides virtualized
+versions of the PIT (in Hyper-V Generation 1 VMs only), local
+APIC timer, and RTC. Hyper-V does not provide a virtualized HPET in
+guest VMs.
+
+The Hyper-V synthetic system clock can be read via a synthetic MSR,
+but this access traps to the hypervisor. As a faster alternative,
+the guest can configure a memory page to be shared between the guest
+and the hypervisor. Hyper-V populates this memory page with a
+64-bit scale value and offset value. To read the synthetic clock
+value, the guest reads the TSC and then applies the scale and offset
+as described in the Hyper-V TLFS. The resulting value advances
+at a constant 10 MHz frequency. In the case of a live migration
+to a host with a different TSC frequency, Hyper-V adjusts the
+scale and offset values in the shared page so that the 10 MHz
+frequency is maintained.
+
+Starting with Windows Server 2022 Hyper-V, Hyper-V uses hardware
+support for TSC frequency scaling to enable live migration of VMs
+across Hyper-V hosts where the TSC frequency may be different.
+When a Linux guest detects that this Hyper-V functionality is
+available, it prefers to use Linux's standard TSC-based clocksource.
+Otherwise, it uses the clocksource for the Hyper-V synthetic system
+clock implemented via the shared page (identified as
+"hyperv_clocksource_tsc_page").
+
+The Hyper-V synthetic system clock is available to user space via
+vDSO, and gettimeofday() and related system calls can execute
+entirely in user space. The vDSO is implemented by mapping the
+shared page with scale and offset values into user space. User
+space code performs the same algorithm of reading the TSC and
+appying the scale and offset to get the constant 10 MHz clock.
+
+Linux clockevents are based on Hyper-V synthetic timer 0. While
+Hyper-V offers 4 synthetic timers for each CPU, Linux only uses
+timer 0. Interrupts from stimer0 are recorded on the "HVS" line in
+/proc/interrupts. Clockevents based on the virtualized PIT and
+local APIC timer also work, but the Hyper-V synthetic timer is
+preferred.
+
+The driver for the Hyper-V synthetic system clock and timers is
+drivers/clocksource/hyperv_timer.c.
diff --git a/Documentation/virt/hyperv/index.rst b/Documentation/virt/hyperv/index.rst
index caa43ab..4a7a1b7 100644
--- a/Documentation/virt/hyperv/index.rst
+++ b/Documentation/virt/hyperv/index.rst
@@ -9,3 +9,4 @@ Hyper-V Enlightenments
overview
vmbus
+ clocks
--
1.8.3.1
On Tue, Jul 05, 2022 at 08:43:42AM -0700, Michael Kelley wrote:
> Add documentation topic for clocks and timers when running as a
> guest on Hyper-V.
>
> Signed-off-by: Michael Kelley <[email protected]>
> ---
> Documentation/virt/hyperv/clocks.rst | 73 ++++++++++++++++++++++++++++++++++++
> Documentation/virt/hyperv/index.rst | 1 +
> 2 files changed, 74 insertions(+)
> create mode 100644 Documentation/virt/hyperv/clocks.rst
>
> diff --git a/Documentation/virt/hyperv/clocks.rst b/Documentation/virt/hyperv/clocks.rst
> new file mode 100644
> index 0000000..e4ba2890
> --- /dev/null
> +++ b/Documentation/virt/hyperv/clocks.rst
> @@ -0,0 +1,73 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Clocks and Timers
> +-----------------
This seems to be inconsistent with regard to the other two files -- they
use "=" signs for the title.
> +
> +arm64
> +~~~~~
And the other files use "-" for this (second?) level.
Thanks,
Wei.
From: Wei Liu <[email protected]> Sent: Wednesday, July 6, 2022 11:26 AM
>
> On Tue, Jul 05, 2022 at 08:43:42AM -0700, Michael Kelley wrote:
> > Add documentation topic for clocks and timers when running as a
> > guest on Hyper-V.
> >
> > Signed-off-by: Michael Kelley <[email protected]>
> > ---
> > Documentation/virt/hyperv/clocks.rst | 73
> ++++++++++++++++++++++++++++++++++++
> > Documentation/virt/hyperv/index.rst | 1 +
> > 2 files changed, 74 insertions(+)
> > create mode 100644 Documentation/virt/hyperv/clocks.rst
> >
> > diff --git a/Documentation/virt/hyperv/clocks.rst
> b/Documentation/virt/hyperv/clocks.rst
> > new file mode 100644
> > index 0000000..e4ba2890
> > --- /dev/null
> > +++ b/Documentation/virt/hyperv/clocks.rst
> > @@ -0,0 +1,73 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +Clocks and Timers
> > +-----------------
>
> This seems to be inconsistent with regard to the other two files -- they
> use "=" signs for the title.
>
> > +
> > +arm64
> > +~~~~~
>
> And the other files use "-" for this (second?) level.
>
Fair point. From what I can see, it actually doesn't make any difference
in how the HTML docs look. I didn't succeed in generating a PDF, so I'm
not sure there. But I'll change the clocks section to match the others
just for consistency.
Michael