Hypervisor in 1,000 Lines

When implementing hypercall handlers, follow the SBI specification conventions:

• Control Transfer: Use ECALL to transfer control from the supervisor to the SEE (Supervisor Execution Environment/Hypervisor).
• Extension ID (EID): Encoded in register a7.
• Function ID (FID): Encoded in register a6 (for SBI v0.2+).
• Register Preservation: The callee must preserve all registers except a0 and a1.
• Return Values: Functions must return a pair of values in a0 and a1, where a0 contains the error code.

The RISC-V hypervisor extension introduces virtualization modes that allow the guest operating system to run with its own user and kernel modes, separate from the host's modes.

• VU-mode (Virtual User mode): The guest's user mode.
• VS-mode (Virtual Supervisor mode): The guest's kernel mode.
• U-mode (User mode): The host's user mode.
• HS-mode (Hypervisor-extended Supervisor mode): The host's kernel mode.

In a hardware-assisted hypervisor, the CPU handles transitions between VU-mode and VS-mode (like guest system calls) automatically. The hypervisor acts as an event handler, primarily intervening during VM exits (e.g., when the guest performs memory-mapped I/O) by jumping to a trap handler.

Hypercalls are the mechanism used by a guest OS to request services from the hypervisor, similar to how system calls work for an OS. The flow is as follows:

1. The guest program executes the ecall instruction with parameters passed in registers.
2. The CPU switches to HS-mode (Hypervisor Supervisor mode) and jumps to the trap handler defined in the stvec CSR.
3. The trap handler saves the guest state and determines the cause of the trap by reading the scause CSR (e.g., an ecall from the guest).
4. After the hypervisor handles the request, the trap handler restores the guest state and returns control to the guest.

In hardware-assisted virtualization (like RISC-V), the CPU uses four address spaces to provide isolation between VMs. When the CPU is in guest mode, address translation occurs in two stages:

1. Stage 1: Guest-virtual $\rightarrow$ guest-physical (controlled by the page table in satp).
2. Stage 2: Guest-physical $\rightarrow$ host-physical (controlled by the guest page table in hgatp).

This two-stage translation allows the hypervisor to map each guest's perceived physical memory to distinct regions of the actual host physical memory, enabling multiple VMs to run simultaneously without direct access to host memory.

To make your allocator thread-safe in a no_std environment, add the spin crate, which provides a Mutex implementation using spinlocks.

$ cargo add spin

To support virtualization modes, you must enable the hypervisor extension in QEMU by adding the h=true flag to the -cpu option.

-cpu rv64,h=true

QEMU is required to emulate the environment where your hypervisor will run. Installation commands vary by operating system:

• macOS: Use Homebrew.
• Ubuntu: Install the RISC-V 64-bit system emulator.
• Windows: Install Windows Subsystem for Linux (WSL2) and follow the Ubuntu instructions.

### macOS
```sh
brew install qemu

Ubuntu

sudo apt install qemu-system-riscv64

Once the global allocator is initialized, you can use dynamic memory features by adding extern crate alloc; to your entry point. Note that you do not need to add alloc to your Cargo.toml as it is bundled with the standard library.

You must explicitly use objects from the alloc crate (e.g., alloc::vec::Vec).

#![no_std]
#![no_main]

extern crate alloc;

fn main() -> ! {
    // Ensure allocator is initialized first
    allocator::GLOBAL_ALLOCATOR.init(&raw mut __heap, &raw mut __heap_end);

    let mut v = alloc::vec::Vec::new();
    v.push('a');
    v.push('b');
    v.push('c');
    
    loop {}
}