Overview

Relevant source files

• .gitignore
• Cargo.toml
• README.md
• src/lib.rs

Purpose and Scope

This document provides an overview of the riscv_vcpu codebase, which implements a RISC-V virtual CPU (VCPU) system designed for hypervisor environments. The system provides virtualization capabilities for RISC-V guest virtual machines running within the ArceOS hypervisor framework.

The riscv_vcpu crate serves as a foundational layer that abstracts RISC-V hardware virtualization features, implements the Supervisor Binary Interface (SBI), and manages virtual CPU lifecycle operations. It requires RISC-V H-extension hardware support to enable efficient guest VM execution with hardware-assisted virtualization.

For detailed information about the core VCPU implementation and execution flow, see Core VCPU Implementation. For system architecture and supporting components, see System Architecture. For low-level assembly and hardware interface details, see Low-Level Implementation.

System Architecture Overview

The RISC-V VCPU system follows a layered architecture that integrates with the ArceOS hypervisor framework while providing hardware-accelerated virtualization for RISC-V guest VMs.

RISC-V VCPU System Architecture

flowchart TD
subgraph subGraph4["Hardware Layer"]
    riscv_h_ext["RISC-V H-ExtensionHardware virtualization support"]
    riscv_core["RISC-V CoreBase ISA + Extensions"]
end
subgraph subGraph3["Low-Level Systems"]
    trap_s["trap.SAssembly trap handlersGuest entry/exit"]
    regs_rs["regs.rsVmCpuRegistersRegister state management"]
    csr_def["def.rsCSR definitionsHardware register interface"]
end
subgraph subGraph2["Core Implementation Layer"]
    vcpu_rs["vcpu.rsRISCVVCpu structVM execution & SBI handling"]
    percpu_rs["percpu.rsRISCVPerCpu structPer-CPU state management"]
    detect_rs["detect.rsdetect_h_extension()Hardware capability detection"]
end
subgraph subGraph1["riscv_vcpu Public Interface"]
    lib_rs["lib.rsRISCVVCpu, RISCVPerCpuhas_hardware_support()"]
    create_config["RISCVVCpuCreateConfighart_id, dtb_addr"]
    eid_hvc["EID_HVCHypercall Extension ID"]
end
subgraph subGraph0["ArceOS Framework Layer"]
    axvcpu["axvcpuVCPU Abstraction"]
    axaddrspace["axaddrspaceAddress Space Management"]
end

axaddrspace --> lib_rs
axvcpu --> lib_rs
create_config --> vcpu_rs
csr_def --> riscv_core
detect_rs --> csr_def
lib_rs --> detect_rs
lib_rs --> percpu_rs
lib_rs --> vcpu_rs
percpu_rs --> csr_def
regs_rs --> csr_def
trap_s --> riscv_h_ext
vcpu_rs --> csr_def
vcpu_rs --> regs_rs
vcpu_rs --> trap_s

Sources: src/lib.rs(L1 - L46)  Cargo.toml(L1 - L26) 

Key Components and Data Flow

The system operates through well-defined interfaces that manage the complete lifecycle of virtual CPU operations, from hardware detection through guest execution.

Component Interaction and Data Flow

flowchart TD
subgraph subGraph3["External Interface"]
    guest_vm["Guest Virtual Machine"]
    host_hypervisor["Host Hypervisor"]
    rustsbi["RustSBI Framework"]
end
subgraph subGraph2["State Management"]
    vm_cpu_regs["VmCpuRegistersregs.rs"]
    csr_setup["setup_csrspercpu.rs"]
    register_sync["Register synchronizationGeneral purpose & CSRs"]
end
subgraph subGraph1["Runtime Execution"]
    guest_entry["_run_guesttrap.S assembly"]
    vm_exit_handler["vmexit_handlervcpu.rs"]
    sbi_processing["SBI call handlingvcpu.rs"]
end
subgraph subGraph0["Initialization Flow"]
    hw_detect["has_hardware_support()detect.rs"]
    percpu_init["RISCVPerCpu::new()percpu.rs"]
    vcpu_create["RISCVVCpu::new()vcpu.rs"]
end

csr_setup --> vm_cpu_regs
guest_entry --> register_sync
guest_entry --> vm_exit_handler
guest_vm --> guest_entry
hw_detect --> percpu_init
percpu_init --> vcpu_create
rustsbi --> guest_vm
sbi_processing --> guest_entry
sbi_processing --> rustsbi
vcpu_create --> csr_setup
vm_exit_handler --> host_hypervisor
vm_exit_handler --> register_sync
vm_exit_handler --> sbi_processing

Sources: src/lib.rs(L18 - L20)  src/vcpu.rs src/percpu.rs src/detect.rs

Hardware Requirements and Dependencies

The RISC-V VCPU system requires specific hardware and software dependencies to function correctly.

The system performs runtime hardware detection using a trap-based mechanism implemented in detect.rs to verify H-extension availability before initializing virtualization capabilities.

Hardware Detection and Initialization Sequence

flowchart TD
start["System Boot"]
hw_check["has_hardware_support()calls detect_h_extension()"]
percpu_new["RISCVPerCpu::new()Initialize per-CPU state"]
hw_fail["Hardware not supportedReturn error"]
csr_init["setup_csrs()Configure hypervisor CSRs"]
vcpu_ready["System ready forVCPU creation"]
vcpu_create["RISCVVCpu::new()with RISCVVCpuCreateConfig"]
guest_ready["Guest VM readyfor execution"]
end_fail["Virtualization unavailable"]
end_success["VCPU operational"]

csr_init --> vcpu_ready
guest_ready --> end_success
hw_check --> hw_fail
hw_check --> percpu_new
hw_fail --> end_fail
percpu_new --> csr_init
start --> hw_check
vcpu_create --> guest_ready
vcpu_ready --> vcpu_create

Sources: src/detect.rs src/lib.rs(L20)  src/percpu.rs

Integration with ArceOS Framework

The riscv_vcpu crate integrates seamlessly with the broader ArceOS hypervisor ecosystem through well-defined interfaces and shared abstractions.

The crate exports three primary interfaces through lib.rs:

• RISCVVCpu<H>: The main virtual CPU implementation
• RISCVPerCpu<H>: Per-CPU state management
• has_hardware_support(): Hardware capability detection function

These components work together to provide a complete RISC-V virtualization solution that abstracts hardware complexity while maintaining high performance through hardware-assisted virtualization features.

Sources: src/lib.rs(L1 - L46)  Cargo.toml(L25 - L26)