Re: [PATCH v16 8/9] doc: add ptp_kvm introduction for arm64 support
From: Marc Zyngier
Date: Tue Feb 02 2021 - 08:59:40 EST
On 2020-12-09 06:09, Jianyong Wu wrote:
PTP_KVM implementation depends on hypercall using SMCCC. So we
introduce a new SMCCC service ID. This doc explains how does the
ID define and how does PTP_KVM works on arm/arm64.
Signed-off-by: Jianyong Wu <jianyong.wu@xxxxxxx>
---
Documentation/virt/kvm/api.rst | 9 +++++++
Documentation/virt/kvm/arm/index.rst | 1 +
Documentation/virt/kvm/arm/ptp_kvm.rst | 31 +++++++++++++++++++++++
Documentation/virt/kvm/timekeeping.rst | 35 ++++++++++++++++++++++++++
4 files changed, 76 insertions(+)
create mode 100644 Documentation/virt/kvm/arm/ptp_kvm.rst
diff --git a/Documentation/virt/kvm/api.rst
b/Documentation/virt/kvm/api.rst
index e00a66d72372..3769cc2f7d9c 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -6390,3 +6390,12 @@ When enabled, KVM will disable paravirtual
features provided to the
guest according to the bits in the KVM_CPUID_FEATURES CPUID leaf
(0x40000001). Otherwise, a guest may use the paravirtual features
regardless of what has actually been exposed through the CPUID leaf.
+
+8.27 KVM_CAP_PTP_KVM
+--------------------
+
+:Architectures: arm64
+
+This capability indicates that KVM virtual PTP service is supported in
host.
+It must company with the implementation of KVM virtual PTP service in
host
+so VMM can probe if there is the service in host by checking this
capability.
This reads a bit odd. I came up with the following:
+This capability indicates that the KVM virtual PTP service is
+supported in the host. A VMM can check whether the service is
+available to the guest on migration.
diff --git a/Documentation/virt/kvm/arm/index.rst
b/Documentation/virt/kvm/arm/index.rst
index 3e2b2aba90fc..78a9b670aafe 100644
--- a/Documentation/virt/kvm/arm/index.rst
+++ b/Documentation/virt/kvm/arm/index.rst
@@ -10,3 +10,4 @@ ARM
hyp-abi
psci
pvtime
+ ptp_kvm
diff --git a/Documentation/virt/kvm/arm/ptp_kvm.rst
b/Documentation/virt/kvm/arm/ptp_kvm.rst
new file mode 100644
index 000000000000..d729c1388a5c
--- /dev/null
+++ b/Documentation/virt/kvm/arm/ptp_kvm.rst
@@ -0,0 +1,31 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+PTP_KVM support for arm/arm64
+=============================
+
+PTP_KVM is used for time sync between guest and host in a high
precision.
+It needs to get the wall time and counter value from the host and
transfer these
+to guest via hypercall service. So one more hypercall service has been
added.
+
+This new SMCCC hypercall is defined as:
It won't be new anymore the minute this is merged.
+
+* ARM_SMCCC_HYP_KVM_PTP_FUNC_ID: 0x86000001
+
+As both 32 and 64-bits ptp_kvm client should be supported, we choose
SMC32/HVC32
+calling convention.
+
+ARM_SMCCC_HYP_KVM_PTP_FUNC_ID:
+
+ ============= ========== ==========
+ Function ID: (uint32) 0x86000001
+ Arguments: (uint32) ARM_PTP_PHY_COUNTER(1) or
ARM_PTP_VIRT_COUNTER(0)
+ which indicate acquiring physical
counter or
+ virtual counter respectively.
+ Return Value: val0(uint32) NOT_SUPPORTED(-1) or upper 32 bits
of wall clock time(64-bits).
+ val1(uint32) Lower 32 bits of wall clock time.
+ val2(uint32) Upper 32 bits of counter
cycle(64-bits).
+ val3(uint32) Lower 32 bits of counter cycle.
+ Endianness: No Restrictions.
+ ============= ========== ==========
+
+More info see section 5 in Documentation/virt/kvm/timekeeping.rst.
I've tidied this up like this:
diff --git a/Documentation/virt/kvm/arm/ptp_kvm.rst
b/Documentation/virt/kvm/arm/ptp_kvm.rst
index d729c1388a5c..68cffb50d8bf 100644
--- a/Documentation/virt/kvm/arm/ptp_kvm.rst
+++ b/Documentation/virt/kvm/arm/ptp_kvm.rst
@@ -3,29 +3,23 @@
PTP_KVM support for arm/arm64
=============================
-PTP_KVM is used for time sync between guest and host in a high
precision.
-It needs to get the wall time and counter value from the host and
transfer these
-to guest via hypercall service. So one more hypercall service has been
added.
-
-This new SMCCC hypercall is defined as:
+PTP_KVM is used for high precision time sync between host and guests.
+It relies on transferring the wall clock and counter value from the
+host to the guest using a KVM-specific hypercall.
* ARM_SMCCC_HYP_KVM_PTP_FUNC_ID: 0x86000001
-As both 32 and 64-bits ptp_kvm client should be supported, we choose
SMC32/HVC32
-calling convention.
-
-ARM_SMCCC_HYP_KVM_PTP_FUNC_ID:
+This hypercall uses the SMC32/HVC32 calling convention:
+ARM_SMCCC_HYP_KVM_PTP_FUNC_ID
============= ========== ==========
Function ID: (uint32) 0x86000001
- Arguments: (uint32) ARM_PTP_PHY_COUNTER(1) or
ARM_PTP_VIRT_COUNTER(0)
- which indicate acquiring physical
counter or
- virtual counter respectively.
- Return Value: val0(uint32) NOT_SUPPORTED(-1) or upper 32 bits
of wall clock time(64-bits).
- val1(uint32) Lower 32 bits of wall clock time.
- val2(uint32) Upper 32 bits of counter
cycle(64-bits).
- val3(uint32) Lower 32 bits of counter cycle.
+ Arguments: (uint32) KVM_PTP_VIRT_COUNTER(0)
+ KVM_PTP_PHYS_COUNTER(1)
+ Return Values: (int32) NOT_SUPPORTED(-1) on error, or
+ (uint32) Upper 32 bits of wall clock time
(r0)
+ (uint32) Lower 32 bits of wall clock time
(r1)
+ (uint32) Upper 32 bits of counter (r2)
+ (uint32) Lower 32 bits of counter (r3)
Endianness: No Restrictions.
============= ========== ==========
-
-More info see section 5 in Documentation/virt/kvm/timekeeping.rst.
diff --git a/Documentation/virt/kvm/timekeeping.rst
b/Documentation/virt/kvm/timekeeping.rst
index 21ae7efa29ba..c81383e38372 100644
--- a/Documentation/virt/kvm/timekeeping.rst
+++ b/Documentation/virt/kvm/timekeeping.rst
@@ -13,6 +13,7 @@ Timekeeping Virtualization for X86-Based
Architectures
2) Timing Devices
3) TSC Hardware
4) Virtualization Problems
+ 5) KVM virtual PTP clock
1. Overview
===========
@@ -643,3 +644,37 @@ by using CPU utilization itself as a signalling
channel. Preventing such
problems would require completely isolated virtual time which may not
track
real time any longer. This may be useful in certain security or QA
contexts,
but in general isn't recommended for real-world deployment scenarios.
+
+5. KVM virtual PTP clock
+========================
+
+NTP (Network Time Protocol) is often used to sync time in a VM.
Unfortunately,
+the precision of NTP is limited due to unknown delays in the network.
+
+KVM virtual PTP clock (PTP_KVM) offers another way to sync time in VM;
use the
+host's clock rather than one from a remote machine. Having a
synchronization
+mechanism for the virtualization environment allows us to keep all the
guests
+running on the same host in sync.
+In general, the delay of communication between host and guest is quite
+small, so ptp_kvm can offer time sync precision up to in order of
nanoseconds.
+Please keep in mind that ptp_kvm just limits itself to be a channel
which
+transmits the remote clock from host to guest. An application, eg.
chrony, is
+needed in usersapce of VM in order to set the guest time.
+
+After ptp_kvm is initialized, there will be a new device node under
/dev called
+ptp%d. A guest userspace service, like chrony, can use this device to
get host
+walltime, sometimes also counter cycle, which depends on the service
it calls.
+Then this guest userspace service can use those data to do the time
sync for
+the guest.
+The following is the work flow of ptp_kvm:
+
+a) time sync service in guest userspace call ioctl on ptp device
/dev/ptp%d.
+b) ptp_kvm module in guest receives this request then invokes
hypercall to
+ route into host kernel to request host's walltime/counter cycle.
+c) ptp_kvm hypercall service on the host responds to the request and
sends data
+ back.
+d) ptp in guest copies the data to userspace.
+
+ptp_kvm consists of components running on the guest and host. Step 2
consists of
+a guest driver making a hypercall whilst step 3 involves the
hypervisor responding
+with information.
I don't think we need any of this here, as the whole file
focuses on x86-specific issues for timekeeping. If we want
to document KVM PTP, this should probably be a separate document.
Thanks,
M.
--
Jazz is not dead. It just smells funny...