System Constants and Trap Definitions

Relevant source files

src/consts.rs

src/vcpu.rs

This document covers the system constants, interrupt types, exception definitions, and trap-related constants used throughout the RISC-V VCPU hypervisor system. These definitions provide the foundation for trap handling, interrupt management, and VM exit processing.

For detailed information about the trap handler assembly implementation, see Trap Handler Implementation. For CSR register definitions used in conjunction with these constants, see CSR Definitions and Hardware Registers.

Trap Constants Architecture

The system defines comprehensive constants for all RISC-V trap types, organized into three main categories: interrupts, exceptions, and IRQ handling. These constants are used throughout the hypervisor for identifying and processing different trap conditions.

Trap Type Hierarchy

flowchart TD
subgraph subGraph3["Trap Constants (consts.rs)"]
    TrapMod["traps module"]
    subgraph subGraph2["IRQ Constants"]
        IrqMod["irq module"]
        IntcBase["INTC_IRQ_BASE = 1<<(usize::BITS-1)"]
        SSoft["S_SOFT = INTC_IRQ_BASE + 1"]
        STimer["S_TIMER = INTC_IRQ_BASE + 5"]
        SExt["S_EXT = INTC_IRQ_BASE + 9"]
        MaxIrq["MAX_IRQ_COUNT = 1024"]
        TimerIrq["TIMER_IRQ_NUM = S_TIMER"]
    end
    subgraph subGraph1["Exception Constants"]
        ExcMod["exception module"]
        InstMisalign["INST_ADDR_MISALIGN = 1<<0"]
        InstFault["INST_ACCESSS_FAULT = 1<<1"]
        IllegalInst["ILLEGAL_INST = 1<<2"]
        Breakpoint["BREAKPOINT = 1<<3"]
        LoadMisalign["LOAD_ADDR_MISALIGNED = 1<<4"]
        LoadFault["LOAD_ACCESS_FAULT = 1<<5"]
        StoreMisalign["STORE_ADDR_MISALIGNED = 1<<6"]
        StoreFault["STORE_ACCESS_FAULT = 1<<7"]
        EnvCallU["ENV_CALL_FROM_U_OR_VU = 1<<8"]
        EnvCallHS["ENV_CALL_FROM_HS = 1<<9"]
        EnvCallVS["ENV_CALL_FROM_VS = 1<<10"]
        EnvCallM["ENV_CALL_FROM_M = 1<<11"]
        InstPageFault["INST_PAGE_FAULT = 1<<12"]
        LoadPageFault["LOAD_PAGE_FAULT = 1<<13"]
        StorePageFault["STORE_PAGE_FAULT = 1<<15"]
        InstGuestFault["INST_GUEST_PAGE_FAULT = 1<<20"]
        LoadGuestFault["LOAD_GUEST_PAGE_FAULT = 1<<21"]
        VirtInst["VIRTUAL_INST = 1<<22"]
        StoreGuestFault["STORE_GUEST_PAGE_FAULT = 1<<23"]
    end
    subgraph subGraph0["Interrupt Constants"]
        IntMod["interrupt module"]
        UserSoft["USER_SOFT = 1<<0"]
        SuperSoft["SUPERVISOR_SOFT = 1<<1"]
        VirtSupSoft["VIRTUAL_SUPERVISOR_SOFT = 1<<2"]
        MachineSoft["MACHINE_SOFT = 1<<3"]
        UserTimer["USER_TIMER = 1<<4"]
        SuperTimer["SUPERVISOR_TIMER = 1<<5"]
        VirtSupTimer["VIRTUAL_SUPERVISOR_TIMER = 1<<6"]
        MachineTimer["MACHINE_TIMER = 1<<7"]
        UserExt["USER_EXTERNAL = 1<<8"]
        SuperExt["SUPERVISOR_EXTERNAL = 1<<9"]
        VirtSupExt["VIRTUAL_SUPERVISOR_EXTERNAL = 1<<10"]
        MachineExt["MACHINEL_EXTERNAL = 1<<11"]
        SuperGuestExt["SUPERVISOR_GUEST_EXTERNEL = 1<<12"]
    end
end

ExcMod --> Breakpoint
ExcMod --> EnvCallHS
ExcMod --> EnvCallM
ExcMod --> EnvCallU
ExcMod --> EnvCallVS
ExcMod --> IllegalInst
ExcMod --> InstFault
ExcMod --> InstGuestFault
ExcMod --> InstMisalign
ExcMod --> InstPageFault
ExcMod --> LoadFault
ExcMod --> LoadGuestFault
ExcMod --> LoadMisalign
ExcMod --> LoadPageFault
ExcMod --> StoreFault
ExcMod --> StoreGuestFault
ExcMod --> StoreMisalign
ExcMod --> StorePageFault
ExcMod --> VirtInst
IntMod --> MachineExt
IntMod --> MachineSoft
IntMod --> MachineTimer
IntMod --> SuperExt
IntMod --> SuperGuestExt
IntMod --> SuperSoft
IntMod --> SuperTimer
IntMod --> UserExt
IntMod --> UserSoft
IntMod --> UserTimer
IntMod --> VirtSupExt
IntMod --> VirtSupSoft
IntMod --> VirtSupTimer
IrqMod --> IntcBase
IrqMod --> MaxIrq
IrqMod --> SExt
IrqMod --> SSoft
IrqMod --> STimer
IrqMod --> TimerIrq
TrapMod --> ExcMod
TrapMod --> IntMod
TrapMod --> IrqMod

Sources: src/consts.rs(L1 - L92)

Interrupt Type Constants

The system defines interrupt constants as bit flags representing different interrupt sources in the RISC-V architecture. These constants are organized by privilege level and interrupt type.

Software Interrupts

Constant	Value	Description
USER_SOFT	1 << 0	User software interrupt
SUPERVISOR_SOFT	1 << 1	Supervisor software interrupt
VIRTUAL_SUPERVISOR_SOFT	1 << 2	Virtual supervisor software interrupt
MACHINE_SOFT	1 << 3	Machine software interrupt

Timer Interrupts

Constant	Value	Description
USER_TIMER	1 << 4	User timer interrupt
SUPERVISOR_TIMER	1 << 5	Supervisor timer interrupt
VIRTUAL_SUPERVISOR_TIMER	1 << 6	Virtual supervisor timer interrupt
MACHINE_TIMER	1 << 7	Machine timer interrupt

External Interrupts

Constant	Value	Description
USER_EXTERNAL	1 << 8	User external interrupt
SUPERVISOR_EXTERNAL	1 << 9	Supervisor external interrupt
VIRTUAL_SUPERVISOR_EXTERNAL	1 << 10	Virtual supervisor external interrupt
MACHINEL_EXTERNAL	1 << 11	Machine external interrupt
SUPERVISOR_GUEST_EXTERNEL	1 << 12	Supervisor guest external interrupt

Sources: src/consts.rs(L4 - L32)

Exception Type Constants

Exception constants define the various fault and trap conditions that can occur during instruction execution. These are used to identify the specific cause of a trap.

Memory Access Exceptions

Constant	Value	Description
INST_ADDR_MISALIGN	1 << 0	Instruction address misaligned
INST_ACCESSS_FAULT	1 << 1	Instruction access fault
LOAD_ADDR_MISALIGNED	1 << 4	Load address misaligned
LOAD_ACCESS_FAULT	1 << 5	Load access fault
STORE_ADDR_MISALIGNED	1 << 6	Store address misaligned
STORE_ACCESS_FAULT	1 << 7	Store access fault

Control Flow Exceptions

Constant	Value	Description
ILLEGAL_INST	1 << 2	Illegal instruction
BREAKPOINT	1 << 3	Breakpoint exception

Environment Call Exceptions

Constant	Value	Description
ENV_CALL_FROM_U_OR_VU	1 << 8	Environment call from U-mode or VU-mode
ENV_CALL_FROM_HS	1 << 9	Environment call from HS-mode
ENV_CALL_FROM_VS	1 << 10	Environment call from VS-mode
ENV_CALL_FROM_M	1 << 11	Environment call from M-mode

Page Fault Exceptions

Constant	Value	Description
INST_PAGE_FAULT	1 << 12	Instruction page fault
LOAD_PAGE_FAULT	1 << 13	Load page fault
STORE_PAGE_FAULT	1 << 15	Store page fault
INST_GUEST_PAGE_FAULT	1 << 20	Instruction guest page fault
LOAD_GUEST_PAGE_FAULT	1 << 21	Load guest page fault
STORE_GUEST_PAGE_FAULT	1 << 23	Store guest page fault

Virtualization Exceptions

Constant	Value	Description
VIRTUAL_INST	1 << 22	Virtual instruction exception

Sources: src/consts.rs(L34 - L74)

IRQ Processing Constants

The IRQ constants provide standardized values for interrupt request processing and scause register interpretation.

Base IRQ Constants

Constant	Value	Description
INTC_IRQ_BASE	1 << (usize::BITS - 1)	Interrupt bit inscauseregister
S_SOFT	INTC_IRQ_BASE + 1	Supervisor software interrupt inscause
S_TIMER	INTC_IRQ_BASE + 5	Supervisor timer interrupt inscause
S_EXT	INTC_IRQ_BASE + 9	Supervisor external interrupt inscause

System Limits

Constant	Value	Description
MAX_IRQ_COUNT	1024	Maximum number of IRQs supported
TIMER_IRQ_NUM	S_TIMER	Timer IRQ number alias

Sources: src/consts.rs(L76 - L91)

Trap Handling Integration

The trap constants are integrated with the VCPU's VM exit handler to provide comprehensive trap processing. The system uses the RISC-V scause register to determine trap types and dispatch to appropriate handlers.

VM Exit Handler Trap Processing

flowchart TD
subgraph subGraph4["Return Values"]
    ExitNothing["AxVCpuExitReason::Nothing"]
    ExitPageFault["AxVCpuExitReason::NestedPageFault"]
    ExitExtInt["AxVCpuExitReason::ExternalInterrupt"]
    ExitHypercall["AxVCpuExitReason::Hypercall"]
    ExitCpuUp["AxVCpuExitReason::CpuUp"]
    ExitSystemDown["AxVCpuExitReason::SystemDown"]
end
subgraph subGraph3["vmexit_handler Function"]
    VmExit["vmexit_handler()"]
    ReadScause["scause::read()"]
    TrapMatch["match scause.cause()"]
    subgraph subGraph2["CSR State Capture"]
        CaptureScause["trap_csrs.scause = scause::read().bits()"]
        CaptureStval["trap_csrs.stval = stval::read()"]
        CaptureHtval["trap_csrs.htval = htval::read()"]
        CaptureHtinst["trap_csrs.htinst = htinst::read()"]
    end
    subgraph subGraph1["Interrupt Handling"]
        SupervisorTimer["SupervisorTimer"]
        SupervisorExternal["SupervisorExternal"]
        TimerHandler["Timer Interrupt Processing"]
        ExtHandler["External Interrupt Processing"]
    end
    subgraph subGraph0["Exception Handling"]
        VSEnvCall["VirtualSupervisorEnvCall"]
        LoadGuestFault["LoadGuestPageFault"]
        StoreGuestFault["StoreGuestPageFault"]
        SBICall["SBI Call Processing"]
        PageFaultHandler["Nested Page Fault"]
    end
end

ExtHandler --> ExitExtInt
LoadGuestFault --> PageFaultHandler
PageFaultHandler --> ExitPageFault
ReadScause --> TrapMatch
SBICall --> ExitCpuUp
SBICall --> ExitHypercall
SBICall --> ExitNothing
SBICall --> ExitSystemDown
StoreGuestFault --> PageFaultHandler
SupervisorExternal --> ExtHandler
SupervisorTimer --> TimerHandler
TimerHandler --> ExitNothing
TrapMatch --> LoadGuestFault
TrapMatch --> StoreGuestFault
TrapMatch --> SupervisorExternal
TrapMatch --> SupervisorTimer
TrapMatch --> VSEnvCall
VSEnvCall --> SBICall
VmExit --> CaptureHtinst
VmExit --> CaptureHtval
VmExit --> CaptureScause
VmExit --> CaptureStval
VmExit --> ReadScause

Sources: src/vcpu.rs(L167 - L308)

Specific Trap Handling Cases

The VCPU system handles several critical trap scenarios using these constants:

SBI Environment Calls

When a VirtualSupervisorEnvCall exception occurs, the system processes SBI (Supervisor Binary Interface) calls by examining the extension ID and function ID in guest registers. This includes:

Legacy SBI calls: Timer, console I/O, and system shutdown
HSM extension: Hart start, stop, and suspend operations
Custom hypercalls: Application-specific hypercall processing
Forwarded calls: Standard SBI extensions handled by RustSBI

Guest Page Faults

The system handles two types of guest page faults:

LoadGuestPageFault: Guest attempted to load from an unmapped or protected page
StoreGuestPageFault: Guest attempted to store to an unmapped or protected page

These faults result in AxVCpuExitReason::NestedPageFault to allow the hypervisor to handle guest memory management.

Timer and External Interrupts

Supervisor Timer Interrupts: Enable guest timer interrupts via hvip::set_vstip()
Supervisor External Interrupts: Forward to hypervisor as AxVCpuExitReason::ExternalInterrupt

Sources: src/vcpu.rs(L184 - L307)

Constant Usage Patterns

The trap constants follow RISC-V specification patterns where:

Bit Position Encoding: Most constants use 1 << N format for bit flag representation
Privilege Level Organization: Constants are grouped by privilege levels (User, Supervisor, Machine)
Interrupt vs Exception: Clear separation between interrupt (asynchronous) and exception (synchronous) constants
IRQ Base Calculation: Uses architecture-specific bit width for interrupt base calculation

These patterns ensure compatibility with RISC-V hardware and provide efficient bit-mask operations for trap classification.

Sources: src/consts.rs(L1 - L92)

AxVisor Crates Book