Model-Specific Register Access

Relevant source files

src/msr.rs

This document covers the Model-Specific Register (MSR) access abstraction layer in the x86_vcpu hypervisor library. MSRs are processor-specific configuration and status registers that control various aspects of CPU behavior, particularly important for VMX virtualization features.

The MSR access system provides a type-safe abstraction over x86 MSR operations, with a focus on VMX-related registers and other MSRs essential for hypervisor operation. For information about VMX-specific data structures and configuration, see VMX Data Structures. For details about VMCS field management, see VMCS Field Management.

MSR Access Architecture

The MSR access system is built around two main components: the Msr enum that defines specific MSR constants, and the MsrReadWrite trait that provides a higher-level abstraction for typed MSR access.

flowchart TD
subgraph subGraph3["VMX Usage"]
    VmxInit["VMX InitializationFeature Detection"]
    VmxConfig["VMX ConfigurationControl Settings"]
    GuestState["Guest StateBase Registers"]
end
subgraph subGraph2["Hardware Interface"]
    X86Crate["x86 craterdmsr() / wrmsr()"]
    Hardware["x86 MSR HardwarePhysical Registers"]
end
subgraph subGraph1["MSR Access Layer"]
    MsrEnum["Msr enumMSR Definitions"]
    MsrReadWriteTrait["MsrReadWrite traitType-safe Access"]
    subgraph subGraph0["Core Methods"]
        ReadMethod["read()Safe MSR Read"]
        WriteMethod["write()Unsafe MSR Write"]
        ReadRaw["read_raw()Trait Default"]
        WriteRaw["write_raw()Trait Default"]
    end
end

GuestState --> MsrEnum
MsrEnum --> ReadMethod
MsrEnum --> WriteMethod
MsrReadWriteTrait --> ReadRaw
MsrReadWriteTrait --> WriteRaw
ReadMethod --> X86Crate
ReadRaw --> ReadMethod
VmxConfig --> MsrEnum
VmxInit --> MsrEnum
WriteMethod --> X86Crate
WriteRaw --> WriteMethod
X86Crate --> Hardware

Sources: src/msr.rs(L1 - L74)

MSR Definitions and Categories

The Msr enum defines specific MSR constants organized by functional categories. Each MSR is represented as a variant with its corresponding hardware register number.

VMX Control and Capability MSRs

The largest category of MSRs relates to VMX virtualization capabilities and control settings:

MSR Name	Value	Purpose
IA32_VMX_BASIC	0x480	Basic VMX capabilities
IA32_VMX_PINBASED_CTLS	0x481	Pin-based VM execution controls
IA32_VMX_PROCBASED_CTLS	0x482	Primary processor-based controls
IA32_VMX_EXIT_CTLS	0x483	VM exit controls
IA32_VMX_ENTRY_CTLS	0x484	VM entry controls
IA32_VMX_PROCBASED_CTLS2	0x48b	Secondary processor-based controls
IA32_VMX_EPT_VPID_CAP	0x48c	EPT and VPID capabilities

flowchart TD
subgraph subGraph5["VMX MSR Categories"]
    subgraph subGraph2["True Controls"]
        TruePinBased["IA32_VMX_TRUE_PINBASED_CTLS0x48d"]
        TrueProcBased["IA32_VMX_TRUE_PROCBASED_CTLS0x48e"]
        TrueExit["IA32_VMX_TRUE_EXIT_CTLS0x48f"]
        TrueEntry["IA32_VMX_TRUE_ENTRY_CTLS0x490"]
    end
    subgraph subGraph1["Control Capabilities"]
        PinBased["IA32_VMX_PINBASED_CTLS0x481"]
        ProcBased["IA32_VMX_PROCBASED_CTLS0x482"]
        ProcBased2["IA32_VMX_PROCBASED_CTLS20x48b"]
        ExitCtls["IA32_VMX_EXIT_CTLS0x483"]
        EntryCtls["IA32_VMX_ENTRY_CTLS0x484"]
    end
    subgraph subGraph0["Basic VMX Info"]
        VmxBasic["IA32_VMX_BASIC0x480Core VMX Features"]
        VmxMisc["IA32_VMX_MISC0x485Miscellaneous Data"]
    end
    subgraph subGraph4["Memory Virtualization"]
        EptVpid["IA32_VMX_EPT_VPID_CAP0x48cEPT & VPID Features"]
        Cr0Fixed0["IA32_VMX_CR0_FIXED00x486"]
    end
    subgraph subGraph3["Fixed Settings"]
        EptVpid["IA32_VMX_EPT_VPID_CAP0x48cEPT & VPID Features"]
        Cr0Fixed0["IA32_VMX_CR0_FIXED00x486"]
        Cr0Fixed1["IA32_VMX_CR0_FIXED10x487"]
        Cr4Fixed0["IA32_VMX_CR4_FIXED00x488"]
        Cr4Fixed1["IA32_VMX_CR4_FIXED10x489"]
    end
end

EntryCtls --> TrueEntry
ExitCtls --> TrueExit
PinBased --> TruePinBased
ProcBased --> ProcBased2
ProcBased --> TrueProcBased
VmxBasic --> EntryCtls
VmxBasic --> ExitCtls
VmxBasic --> PinBased
VmxBasic --> ProcBased

Sources: src/msr.rs(L8 - L28)

System Configuration MSRs

Additional MSRs handle general x86 system configuration:

Feature Control: IA32_FEATURE_CONTROL (0x3a) - Controls processor feature enablement
Memory Management: IA32_PAT (0x277) - Page Attribute Table configuration
Extended State: IA32_XSS (0xda0) - Extended State Save configuration

Long Mode and Segment MSRs

MSRs for 64-bit mode operation and segment base addresses:

Mode Control: IA32_EFER (0xc0000080) - Extended Feature Enable Register
System Call: IA32_STAR, IA32_LSTAR, IA32_CSTAR, IA32_FMASK - System call configuration
Segment Bases: IA32_FS_BASE, IA32_GS_BASE, IA32_KERNEL_GSBASE - Segment base addresses

Sources: src/msr.rs(L8 - L40)

MSR Access Interface

The Msr enum provides direct read and write methods for MSR access:

Read Operations

The read() method provides safe MSR reading:

#![allow(unused)]
fn main() {
pub fn read(self) -> u64
}

This method is marked as #[inline(always)] for performance and uses the x86 crate's rdmsr function internally. Reading MSRs is generally safe as it does not modify processor state.

Write Operations

The write() method provides unsafe MSR writing:

#![allow(unused)]
fn main() {
pub unsafe fn write(self, value: u64)
}

Writing to MSRs is marked as unsafe because incorrect values can cause system instability, crashes, or security vulnerabilities. The caller must ensure that the write operation has no unsafe side effects.

Sources: src/msr.rs(L42 - L59)

MsrReadWrite Trait

The MsrReadWrite trait provides a higher-level abstraction for types that represent specific MSR functionality:

flowchart TD
subgraph subGraph3["MsrReadWrite Trait Pattern"]
    TraitDef["MsrReadWrite traitGeneric MSR Access"]
    subgraph subGraph2["Implementing Types"]
        VmxStructs["VMX Control StructuresType-safe Access"]
        OtherTypes["Other MSR WrappersDomain-specific Logic"]
    end
    subgraph subGraph1["Default Implementations"]
        ReadRawMethod["read_raw() -> u64Self::MSR.read()"]
        WriteRawMethod["write_raw(flags: u64)Self::MSR.write(flags)"]
    end
    subgraph subGraph0["Required Definition"]
        MsrConst["const MSR: MsrAssociated MSR"]
    end
end

OtherTypes --> TraitDef
ReadRawMethod --> MsrConst
TraitDef --> MsrConst
TraitDef --> ReadRawMethod
TraitDef --> WriteRawMethod
VmxStructs --> TraitDef
WriteRawMethod --> MsrConst

The trait defines:

Associated MSR: const MSR: Msr - Links the implementing type to a specific MSR
Raw Read: read_raw() -> u64 - Default implementation calls Self::MSR.read()
Raw Write: unsafe write_raw(flags: u64) - Default implementation calls Self::MSR.write(flags)

This pattern allows creating type-safe wrappers around specific MSRs while maintaining the same underlying access interface.

Sources: src/msr.rs(L61 - L73)

Integration with VMX System

The MSR access system integrates closely with the VMX virtualization engine:

flowchart TD
subgraph subGraph1["Guest Configuration"]
    GuestBase["Guest Segment BasesIA32_*S_BASE"]
    GuestEfer["Guest EFERIA32_EFER"]
    GuestPat["Guest PATIA32_PAT"]
end
subgraph subGraph0["VMX Initialization Flow"]
    FeatureCheck["Feature DetectionIA32_FEATURE_CONTROL"]
    BasicCaps["Capability ReadingIA32_VMX_BASIC"]
    ControlCaps["Control CapabilitiesIA32_VMX_*_CTLS"]
    FixedBits["Fixed Bit RequirementsIA32_VMX_CR*_FIXED*"]
end

BasicCaps --> ControlCaps
ControlCaps --> FixedBits
FeatureCheck --> BasicCaps
FixedBits --> GuestBase
FixedBits --> GuestEfer
FixedBits --> GuestPat

The MSR system enables:

Hardware Capability Discovery - Reading VMX capability MSRs to determine supported features
Control Register Validation - Using fixed bit MSRs to validate CR0/CR4 settings
Guest State Management - Configuring guest segment bases and control registers
Feature Control - Managing processor feature enablement through dedicated MSRs

Sources: src/msr.rs(L8 - L40)

AxVisor Crates Book