[v6,5/5] docs: Add descriptions of TSC scaling in xl.cfg and tscmode.txt

Commit Message

Haozhong Zhang Feb. 28, 2016, 12:54 p.m. UTC

Signed-off-by: Haozhong Zhang <[e-mail]>
Reviewed-by: Kevin Tian <[e-mail]>
---
CC: Ian Campbell <[e-mail]> 
CC: Ian Jackson <[e-mail]>
CC: Jan Beulich <[e-mail]> 
CC: Keir Fraser <[e-mail]> 
CC: Tim Deegan <[e-mail]>
CC: Kevin Tian <[e-mail]>
---
 docs/man/xl.cfg.pod.5 | 14 +++++++++++++-
 docs/misc/tscmode.txt | 21 +++++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)

Comments

Ian Jackson March 1, 2016, 2:09 p.m. UTC | #1

Haozhong Zhang writes ("[PATCH v6 5/5] docs: Add descriptions of TSC scaling in xl.cfg and tscmode.txt"):
> Signed-off-by: Haozhong Zhang <[e-mail]>
> Reviewed-by: Kevin Tian <[e-mail]>

This seems relatively clear.  I'm happy to take your word for it that
this is the behaviour.

If anyone feels that the docs in this patch are wrong, they can send a
followup.  So:

Committed-by: Ian Jackson <[e-mail]>

Ian.

Jan Beulich March 1, 2016, 2:21 p.m. UTC | #2

>>> On 01.03.16 at 15:09, <[e-mail]> wrote:
> Haozhong Zhang writes ("[PATCH v6 5/5] docs: Add descriptions of TSC scaling 
> in xl.cfg and tscmode.txt"):
>> Signed-off-by: Haozhong Zhang <[e-mail]>
>> Reviewed-by: Kevin Tian <[e-mail]>
> 
> This seems relatively clear.  I'm happy to take your word for it that
> this is the behaviour.
> 
> If anyone feels that the docs in this patch are wrong, they can send a
> followup.  So:
> 
> Committed-by: Ian Jackson <[e-mail]>

Oh, thanks. I was about to write a reply asking for a tools side
ack on the xl doc change.

Jan

Patch

diff --git a/docs/man/xl.cfg.pod.5 b/docs/man/xl.cfg.pod.5
index 40690bd..56b1117 100644
--- a/docs/man/xl.cfg.pod.5
+++ b/docs/man/xl.cfg.pod.5
@@ -1313,9 +1313,17 @@  deprecated. Options are:
 
 =item B<"default">
 
-Guest rdtsc/p executed natively when monotonicity can be guaranteed
+Guest rdtsc/p is executed natively when monotonicity can be guaranteed
 and emulated otherwise (with frequency scaled if necessary).
 
+If a HVM container in B<default> TSC mode is created on a host that
+provides constant host TSC, its guest TSC frequency will be the same
+as the host. If it is later migrated to another host that provide
+constant host TSC and supports Intel VMX TSC scaling/AMD SVM TSC
+ratio, its guest TSC frequency will be the same before and after
+migration, and guest rdtsc/p will be executed natively as well after
+migration.
+
 =item B<"always_emulate">
 
 Guest rdtsc/p always emulated at 1GHz (kernel and user). Guest rdtsc/p
@@ -1337,6 +1345,10 @@  determine when a restore/migration has occurred and assumes guest
 obtains/uses pvclock-like mechanism to adjust for monotonicity and
 frequency changes.
 
+If a HVM container in B<native_paravirt> TSC mode can execute both guest
+rdtsc and guest rdtscp natively, then the guest TSC frequency will be
+determined in the similar way to that of B<default> TSC mode.
+
 =back
 
 Please see F<docs/misc/tscmode.txt> for more information on this option.
diff --git a/docs/misc/tscmode.txt b/docs/misc/tscmode.txt
index e8c84e8..01ee060 100644
--- a/docs/misc/tscmode.txt
+++ b/docs/misc/tscmode.txt
@@ -297,3 +297,24 @@  and also much faster than nearly all OS-provided time mechanisms.
 While pvrtscp is too complex for most apps, certain enterprise
 TSC-sensitive high-TSC-frequency apps may find it useful to
 obtain a significant performance gain.
+
+Hardware TSC Scaling
+
+Intel VMX TSC scaling and AMD SVM TSC ratio allow the guest TSC read
+by guest rdtsc/p increasing in a different frequency than the host
+TSC frequency.
+
+If a HVM container in default TSC mode (tsc_mode=0) or PVRDTSCP mode
+(tsc_mode=3) is created on a host that provides constant TSC, its
+guest TSC frequency will be the same as the host. If it is later
+migrated to another host that provides constant TSC and supports Intel
+VMX TSC scaling/AMD SVM TSC ratio, its guest TSC frequency will be the
+same before and after migration.
+
+For above HVM container in default TSC mode (tsc_mode=0), if above
+hosts support rdtscp, both guest rdtsc and rdtscp instructions will be
+executed natively before and after migration.
+
+For above HVM container in PVRDTSCP mode (tsc_mode=3), if the
+destination host does not support rdtscp, the guest rdtscp instruction
+will be emulated with the guest TSC frequency.