kvm: Fix kvmclock documentation to match reality

Commit Message

Stefan Fritsch Sept. 16, 2012, 10:55 a.m. UTC

Hi,

I found the kvmclock documentation to be rather unhelpful. This patch 
should fix it.

Cheers,
Stefan

Author: Stefan Fritsch <[e-mail]>
Date:   Sun Sep 16 12:30:46 2012 +0200

     kvm: Fix kvmclock documentation to match reality

     - mention that system time needs to be added to wallclock time
     - positive tsc_shift means left shift, not right
     - mention additional 32bit right shift

     Signed-off-by: Stefan Fritsch <[e-mail]>

---
  Documentation/virtual/kvm/msr.txt |   32 ++++++++++++++++++++------------
  1 file changed, 20 insertions(+), 12 deletions(-)

--
To unsubscribe from this list: send the line "unsubscribe kvm" in
the body of a message to [e-mail]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Comments

Marcelo Tosatti Sept. 17, 2012, 5:10 p.m. UTC | #1

On Sun, Sep 16, 2012 at 12:55:40PM +0200, Stefan Fritsch wrote:
> Hi,
> 
> I found the kvmclock documentation to be rather unhelpful. This
> patch should fix it.
> 
> Cheers,
> Stefan
> 
> Author: Stefan Fritsch <[e-mail]>
> Date:   Sun Sep 16 12:30:46 2012 +0200
> 
>     kvm: Fix kvmclock documentation to match reality
> 
>     - mention that system time needs to be added to wallclock time
>     - positive tsc_shift means left shift, not right
>     - mention additional 32bit right shift
> 
>     Signed-off-by: Stefan Fritsch <[e-mail]>
> 
> ---
>  Documentation/virtual/kvm/msr.txt |   32 ++++++++++++++++++++------------
>  1 file changed, 20 insertions(+), 12 deletions(-)

Applied, thanks.

--
To unsubscribe from this list: send the line "unsubscribe kvm" in
the body of a message to [e-mail]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Patch

diff --git a/Documentation/virtual/kvm/msr.txt b/Documentation/virtual/kvm/msr.txt
index 7304710..6d470ae 100644
--- a/Documentation/virtual/kvm/msr.txt
+++ b/Documentation/virtual/kvm/msr.txt
@@ -34,9 +34,12 @@  MSR_KVM_WALL_CLOCK_NEW:   0x4b564d00
  		time information and check that they are both equal and even.
  		An odd version indicates an in-progress update.

-		sec: number of seconds for wallclock.
+		sec: number of seconds for wallclock at time of boot.

-		nsec: number of nanoseconds for wallclock.
+		nsec: number of nanoseconds for wallclock at time of boot.
+
+	In order to get the current wallclock time, the system_time from
+	MSR_KVM_SYSTEM_TIME_NEW needs to be added.

  	Note that although MSRs are per-CPU entities, the effect of this
  	particular MSR is global.
@@ -82,20 +85,25 @@  MSR_KVM_SYSTEM_TIME_NEW:  0x4b564d01
  		time at the time this structure was last updated. Unit is
  		nanoseconds.

-		tsc_to_system_mul: a function of the tsc frequency. One has
-		to multiply any tsc-related quantity by this value to get
-		a value in nanoseconds, besides dividing by 2^tsc_shift
+		tsc_to_system_mul: multiplier to be used when converting
+		tsc-related quantity to nanoseconds

-		tsc_shift: cycle to nanosecond divider, as a power of two, to
-		allow for shift rights. One has to shift right any tsc-related
-		quantity by this value to get a value in nanoseconds, besides
-		multiplying by tsc_to_system_mul.
+		tsc_shift: shift to be used when converting tsc-related
+		quantity to nanoseconds. This shift will ensure that
+		multiplication with tsc_to_system_mul does not overflow.
+		A positive value denotes a left shift, a negative value
+		a right shift.

-		With this information, guests can derive per-CPU time by
-		doing:
+		The conversion from tsc to nanoseconds involves an additional
+		right shift by 32 bits. With this information, guests can
+		derive per-CPU time by doing:

  			time = (current_tsc - tsc_timestamp)
-			time = (time * tsc_to_system_mul) >> tsc_shift
+			if (tsc_shift >= 0)
+				time <<= tsc_shift;
+			else
+				time >>= -tsc_shift;
+			time = (time * tsc_to_system_mul) >> 32
  			time = time + system_time

  		flags: bits in this field indicate extended capabilities