English | 中文

Introduction

axaddrspace is the guest address space management crate for the ArceOS-Hypervisor project. It provides nested page table management, guest physical address translation, memory mapping backends, and nested page fault handling for hypervisor environments.

This crate supports multiple architectures:

• x86_64 - VMX Extended Page Tables (EPT)
• AArch64 - Stage-2 page tables
• RISC-V - Nested page tables based on the hypervisor extension

Key capabilities include:

• AddrSpace - address space creation, mapping, unmapping, and translation
• AxMmHal - hardware abstraction trait for frame allocation and address conversion
• Linear mapping backend - map known contiguous host physical memory ranges
• Allocation mapping backend - allocate frames eagerly or lazily on page faults
• Guest memory helpers - translate guest addresses to accessible host buffers

Supports #![no_std] and is intended for bare-metal hypervisor and kernel use.

Quick Start

Requirements

• Rust nightly toolchain
• Rust components: rust-src, clippy, rustfmt

# Install rustup (if not installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install nightly toolchain and components
rustup install nightly
rustup component add rust-src clippy rustfmt --toolchain nightly

Run Check and Test

# 1. Clone the repository
git clone https://github.com/arceos-hypervisor/axaddrspace.git
cd axaddrspace

# 2. Code check
./scripts/check.sh

# 3. Run tests
./scripts/test.sh

# 4. Run a specific integration test target directly
cargo test --test address_space

The helper scripts download the shared axci test/check framework on first run.

Integration

Installation

Add to your Cargo.toml:

[dependencies]
axaddrspace = "0.3.0"

Example

use axaddrspace::{AddrSpace, AxMmHal, GuestPhysAddr, HostPhysAddr, HostVirtAddr, MappingFlags};
use memory_addr::{PhysAddr, VirtAddr};
use page_table_multiarch::PagingHandler;

struct MyHal;

impl AxMmHal for MyHal {
    fn alloc_frame() -> Option<HostPhysAddr> {
        unimplemented!()
    }

    fn dealloc_frame(_paddr: HostPhysAddr) {
        unimplemented!()
    }

    fn phys_to_virt(_paddr: HostPhysAddr) -> HostVirtAddr {
        unimplemented!()
    }

    fn virt_to_phys(_vaddr: HostVirtAddr) -> HostPhysAddr {
        unimplemented!()
    }
}

impl PagingHandler for MyHal {
    fn alloc_frame() -> Option<PhysAddr> {
        <Self as AxMmHal>::alloc_frame()
    }

    fn dealloc_frame(paddr: PhysAddr) {
        <Self as AxMmHal>::dealloc_frame(paddr)
    }

    fn phys_to_virt(paddr: PhysAddr) -> VirtAddr {
        <Self as AxMmHal>::phys_to_virt(paddr)
    }
}

fn example() -> axerrno::AxResult<()> {
    let base = GuestPhysAddr::from_usize(0x1000_0000);
    let mut addr_space = AddrSpace::<MyHal>::new_empty(4, base, 0x20_0000)?;

    addr_space.map_linear(
        base,
        PhysAddr::from_usize(0x8000_0000),
        0x10_0000,
        MappingFlags::READ | MappingFlags::WRITE,
    )?;

    addr_space.map_alloc(
        base + 0x10_0000,
        0x2000,
        MappingFlags::READ | MappingFlags::WRITE,
        false,
    )?;

    let fault_handled = addr_space.handle_page_fault(
        base + 0x10_0000,
        MappingFlags::READ,
    );
    assert!(fault_handled);

    let host_paddr = addr_space.translate(base).unwrap();
    assert_eq!(host_paddr, PhysAddr::from_usize(0x8000_0000));

    Ok(())
}

Features

• arm-el2: enable AArch64 EL2 support
• default: includes arm-el2

Documentation

Generate and view API documentation:

cargo doc --no-deps --open

Online documentation: docs.rs/axaddrspace

Contributing

1. Fork the repository and create a branch
2. Run local check: ./scripts/check.sh
3. Run local tests: ./scripts/test.sh
4. Submit PR and pass CI checks

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.