From patchwork Wed May 26 18:04:48 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Glauber Costa X-Patchwork-Id: 102462 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by demeter.kernel.org (8.14.3/8.14.3) with ESMTP id o4QIC9iE027114 for ; Wed, 26 May 2010 18:12:09 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1757301Ab0EZSLp (ORCPT ); Wed, 26 May 2010 14:11:45 -0400 Received: from mx1.redhat.com ([209.132.183.28]:2593 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1757078Ab0EZSLo (ORCPT ); Wed, 26 May 2010 14:11:44 -0400 Received: from int-mx08.intmail.prod.int.phx2.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o4QIBi7j011586 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 26 May 2010 14:11:44 -0400 Received: from localhost.localdomain (virtlab1.virt.bos.redhat.com [10.16.72.21]) by int-mx08.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o4QIBh1A002848; Wed, 26 May 2010 14:11:43 -0400 From: Glauber Costa To: kvm@vger.kernel.org Cc: linux-kernel@vger.kernel.org, avi@redhat.com, zamsden@redhat.com Subject: [PATCH] Add Documentation/kvm/msr.txt Date: Wed, 26 May 2010 14:04:48 -0400 Message-Id: <1274897088-8587-1-git-send-email-glommer@redhat.com> X-Scanned-By: MIMEDefang 2.67 on 10.5.11.21 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org X-Greylist: IP, sender and recipient auto-whitelisted, not delayed by milter-greylist-4.2.3 (demeter.kernel.org [140.211.167.41]); Wed, 26 May 2010 18:12:09 +0000 (UTC) diff --git a/Documentation/kvm/msr.txt b/Documentation/kvm/msr.txt new file mode 100644 index 0000000..c5110a2 --- /dev/null +++ b/Documentation/kvm/msr.txt @@ -0,0 +1,115 @@ +KVM-specific MSRs. +Glauber Costa , Red Hat Inc, 2010 +===================================================== + +KVM makes use of some custom MSRs to service some requests. +At present, this facility is only used by kvmclock. + +Custom MSRs have a range reserved for them, that goes from +0x4b564d00 to 0x4b564dff. There are MSRs outside this area, +but they are deprecated and their use is discouraged. + +Custom MSR list +-------- + +The current supported Custom MSR list is: + +MSR_KVM_WALL_CLOCK: 0x11 + + data: physical address of a memory area. This memory is expected to + hold a copy of the following structure: + + struct pvclock_wall_clock { + u32 version; + u32 sec; + u32 nsec; + } __attribute__((__packed__)); + + whose data will be filled in by the hypervisor. The hypervisor will only + touch this data once, at the moment of MSR write. Users that want to + query this information more than once, have to write more than once to + this MSR. Fields has the following meaning: + + version: guest has to check version before and after grabbing + 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. + + nsec: number of nanoseconds for wallclock. + + Note that, although MSRs are per-CPU entities, the effect of this + particular MSR is global. + + Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid + leaf prior to usage. + + This MSR falls outside the reserved KVM range, and may be removed in the + future. Its usage is deprecated. + +MSR_KVM_SYSTEM_TIME: 0x12 + + data: physical address of a memory area. This memory is expected to + hold a copy of the following structure: + + struct pvclock_vcpu_time_info { + u32 version; + u32 pad0; + u64 tsc_timestamp; + u64 system_time; + u32 tsc_to_system_mul; + s8 tsc_shift; + u8 flags; + u8 pad[2]; + } __attribute__((__packed__)); /* 32 bytes */ + + whose data will be filled in by the hypervisor periodically. Only one + write, or registration, is needed for each VCPU. The interval between + updates of this structure is arbitrary, and implementation-dependent. + + version: guest has to check version before and after grabbing + time information, and check that they are both equal and even. + An odd version indicates an in-progress update. + + tsc_timestamp: the tsc value at the current VCPU, at the time + of the update of this structure. Guests can subtract this value + from current tsc to derive a notion of elapsed time since the + structure update. + + system_time: the current system 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_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. + + flags: bits in this field indicate extended capabilities + coordinated between the guest and the hypervisor. Availability + of specific flags has to be checked in 0x40000001 cpuid leaf. + Refer to cpuid.txt for details. + + Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid + leaf prior to usage. + + This MSR falls outside the reserved KVM range, and may be removed in the + future. Its usage is deprecated. + +MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00 + + data and functioning: same as MSR_KVM_WALL_CLOCK. Use this instead. + + Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid + leaf prior to usage. + +MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 + + data and functioning: same as MSR_KVM_SYSTEM_TIME. Use this instead. + + Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid + leaf prior to usage. +