Kernel-4.18.0-80.el8_msr

KVM-specific MSRs.
Glauber Costa glommer@redhat.com, Red Hat Inc, 2010
=====================================================

KVM makes use of some custom MSRs to service some requests.

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_NEW: 0x4b564d00

data: 4-byte alignment physical address of a memory area which must be
in guest RAM. 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 is only
guaranteed to update this data at the moment of MSR write.
Users that want to reliably query this information more than once have
to write more than once to this MSR. Fields have the following meanings:

    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 at time of boot.

    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.

Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
leaf prior to usage.

MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01

data: 4-byte aligned physical address of a memory area which must be in
guest RAM, plus an enable bit in bit 0. 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.
The hypervisor may update this structure at any time it sees fit until
anything with bit0 == 0 is written to it.

Fields have the following meanings:

    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: a host notion of monotonic time, including sleep
    time at the time this structure was last updated. Unit is
    nanoseconds.

    tsc_to_system_mul: multiplier to be used when converting
    tsc-related quantity to nanoseconds

    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.

    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)
        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
    coordinated between the guest and the hypervisor. Availability
    of specific flags has to be checked in 0x40000001 cpuid leaf.
    Current flags are:

     flag bit   | cpuid bit    | meaning
    -------------------------------------------------------------
            |               | time measures taken across
         0      |       24      | multiple cpus are guaranteed to
            |           | be monotonic
    -------------------------------------------------------------
            |           | guest vcpu has been paused by
         1        |      N/A       | the host
            |           | See 4.70 in api.txt
    -------------------------------------------------------------

Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid
leaf prior to usage.

MSR_KVM_WALL_CLOCK: 0x11

data and functioning: same as MSR_KVM_WALL_CLOCK_NEW. Use that instead.

This MSR falls outside the reserved KVM range and may be removed in the
future. Its usage is deprecated.

Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
leaf prior to usage.

MSR_KVM_SYSTEM_TIME: 0x12

data and functioning: same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead.

This MSR falls outside the reserved KVM range and may be removed in the
future. Its usage is deprecated.

Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid
leaf prior to usage.

The suggested algorithm for detecting kvmclock presence is then:

    if (!kvm_para_available())    /* refer to cpuid.txt */
        return NON_PRESENT;

    flags = cpuid_eax(0x40000001);
    if (flags & 3) {
        msr_kvm_system_time = MSR_KVM_SYSTEM_TIME_NEW;
        msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK_NEW;
        return PRESENT;
    } else if (flags & 0) {
        msr_kvm_system_time = MSR_KVM_SYSTEM_TIME;
        msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK;
        return PRESENT;
    } else
        return NON_PRESENT;

MSR_KVM_ASYNC_PF_EN: 0x4b564d02
data: Bits 63-6 hold 64-byte aligned physical address of a
64 byte memory area which must be in guest RAM and must be
zeroed. Bits 5-3 are reserved and should be zero. Bit 0 is 1
when asynchronous page faults are enabled on the vcpu 0 when
disabled. Bit 1 is 1 if asynchronous page faults can be injected
when vcpu is in cpl == 0. Bit 2 is 1 if asynchronous page faults
are delivered to L1 as #PF vmexits. Bit 2 can be set only if
KVM_FEATURE_ASYNC_PF_VMEXIT is present in CPUID.

First 4 byte of 64 byte memory location will be written to by
the hypervisor at the time of asynchronous page fault (APF)
injection to indicate type of asynchronous page fault. Value
of 1 means that the page referred to by the page fault is not
present. Value 2 means that the page is now available. Disabling
interrupt inhibits APFs. Guest must not enable interrupt
before the reason is read, or it may be overwritten by another
APF. Since APF uses the same exception vector as regular page
fault guest must reset the reason to 0 before it does
something that can generate normal page fault.  If during page
fault APF reason is 0 it means that this is regular page
fault.

During delivery of type 1 APF cr2 contains a token that will
be used to notify a guest when missing page becomes
available. When page becomes available type 2 APF is sent with
cr2 set to the token associated with the page. There is special
kind of token 0xffffffff which tells vcpu that it should wake
up all processes waiting for APFs and no individual type 2 APFs
will be sent.

If APF is disabled while there are outstanding APFs, they will
not be delivered.

Currently type 2 APF will be always delivered on the same vcpu as
type 1 was, but guest should not rely on that.

MSR_KVM_STEAL_TIME: 0x4b564d03

data: 64-byte alignment physical address of a memory area which must be
in guest RAM, plus an enable bit in bit 0. This memory is expected to
hold a copy of the following structure:

struct kvm_steal_time {
    __u64 steal;
    __u32 version;
    __u32 flags;
    __u8  preempted;
    __u8  u8_pad[3];
    __u32 pad[11];
}

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.
The hypervisor may update this structure at any time it sees fit until
anything with bit0 == 0 is written to it. Guest is required to make sure
this structure is initialized to zero.

Fields have the following meanings:

    version: a sequence counter. In other words, guest has to check
    this field before and after grabbing time information and make
    sure they are both equal and even. An odd version indicates an
    in-progress update.

    flags: At this point, always zero. May be used to indicate
    changes in this structure in the future.

    steal: the amount of time in which this vCPU did not run, in
    nanoseconds. Time during which the vcpu is idle, will not be
    reported as steal time.

    preempted: indicate the vCPU who owns this struct is running or
    not. Non-zero values mean the vCPU has been preempted. Zero
    means the vCPU is not preempted. NOTE, it is always zero if the
    the hypervisor doesn't support this field.

MSR_KVM_EOI_EN: 0x4b564d04
data: Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0
when disabled. Bit 1 is reserved and must be zero. When PV end of
interrupt is enabled (bit 0 set), bits 63-2 hold a 4-byte aligned
physical address of a 4 byte memory area which must be in guest RAM and
must be zeroed.

The first, least significant bit of 4 byte memory location will be
written to by the hypervisor, typically at the time of interrupt
injection.  Value of 1 means that guest can skip writing EOI to the apic
(using MSR or MMIO write); instead, it is sufficient to signal
EOI by clearing the bit in guest memory - this location will
later be polled by the hypervisor.
Value of 0 means that the EOI write is required.

It is always safe for the guest to ignore the optimization and perform
the APIC EOI write anyway.

Hypervisor is guaranteed to only modify this least
significant bit while in the current VCPU context, this means that
guest does not need to use either lock prefix or memory ordering
primitives to synchronise with the hypervisor.

However, hypervisor can set and clear this memory bit at any time:
therefore to make sure hypervisor does not interrupt the
guest and clear the least significant bit in the memory area
in the window between guest testing it to detect
whether it can skip EOI apic write and between guest
clearing it to signal EOI to the hypervisor,
guest must both read the least significant bit in the memory area and
clear it using a single CPU instruction, such as test and clear, or
compare and exchange.