riscv-h

RISC-V Hypervisor Extension Register Support

A Rust crate providing low-level access to RISC-V hypervisor extension registers. This crate implements the hypervisor Control and Status Registers (CSRs) defined in the RISC-V Hypervisor Extension specification, enabling virtualization support on RISC-V processors.

Features

• No-std compatible: Designed for bare-metal and OS kernel development
• Type-safe register access: Bitfield manipulation with compile-time safety
• Comprehensive CSR coverage: All hypervisor and virtual supervisor registers
• Well-tested: Extensive unit tests for all register implementations

Supported Registers

Hypervisor Control Registers

Virtual Supervisor Registers

Additional Registers

• Interrupt Management: hip, hvip, hgeie, hgeip
• Time Management: htimedelta, htimedeltah
• Trap Information: htval, htinst
• Virtual Supervisor Interrupts: vsip

Quick Start

Add this crate to your Cargo.toml:

[dependencies]
riscv-h = "0.1.0"

Basic Usage

#![no_std]

use riscv_h::register::{hstatus, hgatp};

fn setup_hypervisor() {
    // Read current hypervisor status
    let hstatus = hstatus::read();
    
    // Check if we're in virtualized mode
    if hstatus.spv() {
        // Handle virtualized context
        setup_guest_translation();
    }
}

fn setup_guest_translation() {
    unsafe {
        // Configure guest address translation
        let mut hgatp = hgatp::Hgatp::from_bits(0);
        hgatp.set_mode(hgatp::HgatpValues::Sv48x4);
        hgatp.set_vmid(1);
        hgatp.set_ppn(0x1000); // Root page table PPN
        hgatp.write();
    }
}

Register Field Access

use riscv_h::register::hstatus;

// Read register value
let hstatus_val = hstatus::read();

// Access individual fields
let vsxl = hstatus_val.vsxl();      // Virtual supervisor XLEN
let vtw = hstatus_val.vtw();        // Trap WFI
let vtsr = hstatus_val.vtsr();      // Trap SRET
let vgein = hstatus_val.vgein();    // Virtual guest external interrupt number

// Modify register (create new value)
let mut new_hstatus = hstatus::Hstatus::from_bits(0);
new_hstatus.set_vtw(true);          // Enable WFI trapping
new_hstatus.set_hu(true);           // Enable hypervisor user mode

unsafe {
    new_hstatus.write();             // Write to CSR
}

Exception and Interrupt Delegation

use riscv_h::register::{hedeleg, hideleg};

unsafe {
    // Delegate common exceptions to VS-mode
    hedeleg::set_ex2(true);  // Illegal instruction
    hedeleg::set_ex8(true);  // Environment call from U-mode
    hedeleg::set_ex12(true); // Instruction page fault
    hedeleg::set_ex13(true); // Load page fault
    hedeleg::set_ex15(true); // Store page fault
    
    // Delegate timer and software interrupts to VS-mode
    hideleg::set_vstie(true);  // VS-mode timer interrupt
    hideleg::set_vssie(true);  // VS-mode software interrupt
}

Architecture Support

• RISC-V 64-bit (RV64): Full support for all hypervisor extension registers
• Privilege Levels: HS-mode, VS-mode, VU-mode register access
• Memory Management: Two-stage address translation support

Safety

This crate provides unsafe functions for writing to CSRs, as register modifications can affect system behavior. Users must ensure:

• Proper privilege level (HS-mode) when accessing hypervisor CSRs
• Valid field values according to RISC-V specification
• Correct synchronization when modifying shared state

License

This project is licensed under multiple licenses:

• GNU General Public License v3.0 or later
• Apache License 2.0
• Mulan PSL v2

See the LICENSE files for details.

Contributing

Contributions are welcome! Please:

1. Follow the existing code style and conventions
2. Add tests for new register implementations
3. Update documentation for any API changes
4. Ensure all tests pass before submitting

References

• RISC-V Hypervisor Extension Specification
• RISC-V Privileged Architecture Specification
• riscv crate - Base RISC-V register support