CSR Definitions and Hardware Registers

Relevant source files

• .github/workflows/ci.yml
• def.rs
• src/percpu.rs

This document provides comprehensive reference material for the Control and Status Register (CSR) definitions and hardware register interfaces used throughout the RISC-V VCPU hypervisor system. It covers the register bitfield definitions, CSR initialization procedures, and the hierarchical organization of supervisor, virtual supervisor, and hypervisor-level registers.

For information about trap handling and exception processing that utilizes these CSRs, see Trap Handler Implementation. For system constants and trap definitions, see System Constants and Trap Definitions.

CSR Architecture Overview

The RISC-V hypervisor extension introduces a three-level privilege hierarchy that requires careful management of CSRs across supervisor, virtual supervisor, and hypervisor modes. The system implements comprehensive CSR definitions using the tock_registers framework to provide type-safe register access.

Register Hierarchy and Privilege Levels

flowchart TD
subgraph subGraph2["Virtual Supervisor Mode (VS-level)"]
    VSSTATUS["VSSTATUSVirtual Supervisor Status"]
    VSIE["VSIEVirtual Supervisor IE"]
    VSTVEC["VSTVECVirtual Trap Vector"]
    VSSCRATCH["VSSCRATCHVirtual Scratch"]
    VSEPC["VSEPCVirtual Exception PC"]
    VSCAUSE["VSCAUSEVirtual Exception Cause"]
    VSTVAL["VSTVALVirtual Trap Value"]
    VSATP["VSATPVirtual Address Translation"]
end
subgraph subGraph1["Supervisor Mode (S-level)"]
    SSTATUS["SSTATUSSupervisor Status"]
    SIE["SIESupervisor Interrupt Enable"]
    STVEC["STVECTrap Vector"]
    SSCRATCH["SSCRATCHScratch Register"]
    SEPC["SEPCException PC"]
    SCAUSE["SCAUSEException Cause"]
    STVAL["STVALTrap Value"]
    SATP["SATPAddress Translation"]
end
subgraph subGraph0["Hypervisor Mode (HS-level)"]
    HSTATUS["HSTATUSHypervisor Status"]
    HEDELEG["HEDELEGException Delegation"]
    HIDELEG["HIDELEGInterrupt Delegation"]
    HIE["HIEHypervisor Interrupt Enable"]
    HVIP["HVIPVirtual Interrupt Pending"]
    HCOUNTEREN["HCOUNTERENCounter Enable"]
    HGATP["HGATPGuest Address Translation"]
end

HEDELEG --> SCAUSE
HIDELEG --> SIE
HSTATUS --> VSSTATUS
HVIP --> VSIE

Sources: def.rs(L1 - L52)  src/percpu.rs(L44 - L81) 

CSR Address Space Organization

flowchart TD
subgraph Implementation_Modules["Implementation_Modules"]
    SIE_Impl["sie moduleSupervisor Interrupt Enable"]
    HSTATUS_Impl["hstatus moduleHypervisor Status"]
    HEDELEG_Impl["hedeleg moduleException Delegation"]
    HIDELEG_Impl["hideleg moduleInterrupt Delegation"]
    HIE_Impl["hie moduleHypervisor Interrupt Enable"]
    HCOUNTEREN_Impl["hcounteren moduleCounter Enable"]
    HVIP_Impl["hvip moduleVirtual Interrupt Pending"]
end
subgraph CSR_Address_Space["CSR_Address_Space"]
    S_Range["0x100-0x1FFSupervisor CSRs"]
    VS_Range["0x200-0x2FFVirtual Supervisor CSRs"]
    H_Range["0x600-0x6FFHypervisor CSRs"]
    M_Range["0x300-0x3FFMachine CSRs"]
end

H_Range --> HCOUNTEREN_Impl
H_Range --> HEDELEG_Impl
H_Range --> HIDELEG_Impl
H_Range --> HIE_Impl
H_Range --> HSTATUS_Impl
H_Range --> HVIP_Impl
S_Range --> SIE_Impl

Sources: def.rs(L4 - L52)  def.rs(L551 - L684)  def.rs(L687 - L1284) 

CSR Initialization Process

The system initializes CSRs through the setup_csrs() function called during per-CPU initialization. This process configures exception delegation, interrupt delegation, and enables necessary hardware features.

CSR Setup Flow

flowchart TD
subgraph Exception_Types["Exception_Types"]
    LOAD_PAGE_FAULT["LOAD_PAGE_FAULT"]
    STORE_PAGE_FAULT["STORE_PAGE_FAULT"]
    ILLEGAL_INST["ILLEGAL_INST"]
    Start["setup_csrs()"]
    subgraph Interrupt_Types["Interrupt_Types"]
        VIRTUAL_SUPERVISOR_TIMER["VIRTUAL_SUPERVISOR_TIMER"]
        VIRTUAL_SUPERVISOR_EXTERNAL["VIRTUAL_SUPERVISOR_EXTERNAL"]
        VIRTUAL_SUPERVISOR_SOFT["VIRTUAL_SUPERVISOR_SOFT"]
        INST_ADDR_MISALIGN["INST_ADDR_MISALIGN"]
        BREAKPOINT["BREAKPOINT"]
        ENV_CALL_FROM_U_OR_VU["ENV_CALL_FROM_U_OR_VU"]
        INST_PAGE_FAULT["INST_PAGE_FAULT"]
    end
end
HEDELEG_Setup["Configure HEDELEGException Delegation"]
HIDELEG_Setup["Configure HIDELEGInterrupt Delegation"]
HVIP_Clear["Clear HVIPVirtual Interrupts"]
HCOUNTEREN_Set["Set HCOUNTERENCounter Access"]
SIE_Enable["Enable SIESupervisor Interrupts"]
Complete["CSR Setup Complete"]

HCOUNTEREN_Set --> SIE_Enable
HEDELEG_Setup --> HIDELEG_Setup
HIDELEG_Setup --> HVIP_Clear
HVIP_Clear --> HCOUNTEREN_Set
SIE_Enable --> Complete
Start --> HEDELEG_Setup

Sources: src/percpu.rs(L44 - L81) 

Key CSR Register Definitions

Hypervisor Exception Delegation Register (HEDELEG)

The hedeleg module provides bitfield definitions for configuring which exceptions are delegated to lower privilege levels. Each bit corresponds to a specific exception type defined in the trap constants.

Sources: def.rs(L55 - L547) 

Hypervisor Status Register (HSTATUS)

The hstatus module defines the hypervisor status register with fields controlling virtualization behavior and guest state management.

Sources: def.rs(L687 - L1284) 

Supervisor Interrupt Enable Register (SIE)

The sie module provides definitions for enabling specific interrupt types at the supervisor level.

Sources: def.rs(L551 - L684) 

Virtual Interrupt Management

The system provides comprehensive virtual interrupt management through several CSR modules:

flowchart TD
subgraph Control_Operations["Control_Operations"]
    Delegate["hideleg.write()Delegate interrupts"]
    Enable["hie.write()Enable interrupts"]
    Inject["hvip.set_*()Inject interrupts"]
    Clear["hvip.clear_*()Clear interrupts"]
end
subgraph Interrupt_Types["Interrupt_Types"]
    VSSOFT["vssoftBit 2VS-mode software"]
    VSTIMER["vstimerBit 6VS-mode timer"]
    VSEXT["vsextBit 10VS-mode external"]
    SGEXT["sgextBit 12Supervisor guest external"]
end
subgraph Virtual_Interrupt_Control["Virtual_Interrupt_Control"]
    HIDELEG_CSR["hideleg CSR0x603"]
    HIE_CSR["hie CSR0x604"]
    HVIP_CSR["hvip CSR0x645"]
end

Delegate --> VSEXT
Delegate --> VSSOFT
Delegate --> VSTIMER
Enable --> SGEXT
HIDELEG_CSR --> Delegate
HIE_CSR --> Enable
HVIP_CSR --> Clear
HVIP_CSR --> Inject

Sources: def.rs(L1287 - L1596)  def.rs(L1422 - L1596)  def.rs(L1774 - L1908) 

CSR Usage in System Initialization

The RISCVPerCpu implementation demonstrates practical CSR usage during system initialization. The setup_csrs() function configures the hypervisor environment for guest execution.

Exception Delegation Configuration

flowchart TD
subgraph Delegated_Exceptions["Delegated_Exceptions"]
    INST_ADDR_MISALIGN_BIT["INST_ADDR_MISALIGN"]
    BREAKPOINT_BIT["BREAKPOINT"]
    ENV_CALL_BIT["ENV_CALL_FROM_U_OR_VU"]
    INST_PAGE_FAULT_BIT["INST_PAGE_FAULT"]
    LOAD_PAGE_FAULT_BIT["LOAD_PAGE_FAULT"]
    STORE_PAGE_FAULT_BIT["STORE_PAGE_FAULT"]
    ILLEGAL_INST_BIT["ILLEGAL_INST"]
end
subgraph setup_csrs_function["setup_csrs_function"]
    HEDELEG_Config["hedeleg::Hedeleg::from_bits()"]
    Exception_Mask["traps::exception bitmask"]
    HEDELEG_Write["hedeleg.write()"]
end

BREAKPOINT_BIT --> Exception_Mask
ENV_CALL_BIT --> Exception_Mask
Exception_Mask --> HEDELEG_Config
HEDELEG_Config --> HEDELEG_Write
ILLEGAL_INST_BIT --> Exception_Mask
INST_ADDR_MISALIGN_BIT --> Exception_Mask
INST_PAGE_FAULT_BIT --> Exception_Mask
LOAD_PAGE_FAULT_BIT --> Exception_Mask
STORE_PAGE_FAULT_BIT --> Exception_Mask

Counter Enable Configuration

The system includes a workaround for the hcounteren CSR due to an error in the riscv crate. Direct assembly is used to write the correct CSR address:

// Direct CSR write due to riscv crate error
core::arch::asm!("csrw {csr}, {rs}", csr = const 0x606, rs = in(reg) -1);

Sources: src/percpu.rs(L72 - L74) 

Register Access Patterns

The CSR definitions use the tock_registers framework to provide type-safe register access with clear field semantics. Each register module includes:

• Field definitions with bit positions and widths
• Value enumerations for multi-bit fields
• SET/CLEAR constants for single-bit fields
• Type-safe conversion functions between values and register representations

Field Value Operations

flowchart TD
subgraph Usage_Examples["Usage_Examples"]
    HSTATUS_SPV["hstatus::spv::Supervisor"]
    SIE_SEXT["sie::sext::SET"]
    HVIP_CLEAR["hvip::vstimer::CLEAR"]
end
subgraph Register_Field_Operations["Register_Field_Operations"]
    FieldValue["FieldValue"]
    SET_Const["Field::SET constant"]
    CLEAR_Const["Field::CLEAR constant"]
    Custom_Value["Custom value creation"]
end

CLEAR_Const --> HVIP_CLEAR
Custom_Value --> HSTATUS_SPV
FieldValue --> CLEAR_Const
FieldValue --> Custom_Value
FieldValue --> SET_Const
SET_Const --> SIE_SEXT

Sources: def.rs(L783 - L881)  def.rs(L578 - L603)  def.rs(L853 - L867)