arceos-hashmap

A standalone ArceOS unikernel exercise (arceos-hashmap): enable collections::HashMap under axstd, with dependencies from crates.io, multi-architecture builds and QEMU runs via cargo xtask.

This repository is the exercise.

Supported Architectures

Architecture	Rust Target	QEMU Machine	Platform
riscv64	riscv64gc-unknown-none-elf	qemu-system-riscv64 -machine virt	riscv64-qemu-virt
aarch64	aarch64-unknown-none-softfloat	qemu-system-aarch64 -machine virt	aarch64-qemu-virt
x86_64	x86_64-unknown-none	qemu-system-x86_64 -machine q35	x86-pc
loongarch64	loongarch64-unknown-none	qemu-system-loongarch64 -machine virt	loongarch64-qemu-virt

Prerequisites

• Rust nightly toolchain (edition 2024)

  rustup install nightly
  rustup default nightly

• Bare-metal targets (install the ones you need)

  rustup target add riscv64gc-unknown-none-elf
  rustup target add aarch64-unknown-none-softfloat
  rustup target add x86_64-unknown-none
  rustup target add loongarch64-unknown-none

• QEMU (install the emulators for your target architectures)

  # Ubuntu/Debian
  sudo apt install qemu-system-riscv64 qemu-system-aarch64 \
                   qemu-system-x86 qemu-system-loongarch64  # OR qemu-systrem-misc
  
  # macOS (Homebrew)
  brew install qemu

• rust-objcopy (from cargo-binutils, required for non-x86_64 targets)

  cargo install cargo-binutils
  rustup component add llvm-tools

Quick Start

Get Source Code

Method 1: Get source code from crates.io

# install cargo-clone sub-command
cargo install cargo-clone
# get source code of arceos-hashmap crate from crates.io
cargo clone arceos-hashmap
# into crate dir
cd arceos-hashmap

Method 2: Clone the tg-arceos-tutorial repository

git clone https://github.com/arceos-org/tg-arceos-tutorial.git
cd tg-arceos-tutorial/exercise-hashmap

Build & Run

# Build and run on RISC-V 64 QEMU (default)
cargo xtask run

# Build and run on other architectures
cargo xtask run --arch aarch64
cargo xtask run --arch x86_64
cargo xtask run --arch loongarch64

# Build only (no QEMU)
cargo xtask build --arch riscv64
cargo xtask build --arch aarch64

Exercise

Requirements

Implement support for collections::HashMap in axstd.

The axstd crate published on crates.io does not yet provide an implementation for collections::HashMap. Therefore, this repository will fail to compile unless you modify axstd locally to add this support.

Expectation

Serial output should include:

test_hashmap() OK!
Memory tests run OK!

Verification

• The serial output must contain test_hashmap() OK!.
• The serial output must contain Memory tests run OK!.

Run the test script:

bash scripts/test.sh

Tips

1. If compiler errors mention std, that name refers to axstd: the application uses extern crate axstd as std; in src/main.rs.
2. A random number helper random() is available in axhal, which you can use when wiring randomness for HashMap (e.g. default hasher behavior).
3. To hack on ArceOS crates locally, clone the crate and switch the dependency in Cargo.toml from a version requirement to path:

cargo clone axstd@0.3.0-preview.1

[dependencies]
axstd = { path = "./axstd", features = ["defplat", "alloc"], optional = true }

(Adjust the path to match where you put the sources.)

Project Structure

exercise-hashmap/
├── .cargo/
│   └── config.toml       # cargo xtask alias
├── configs/
│   ├── riscv64.toml
│   ├── aarch64.toml
│   ├── x86_64.toml
│   └── loongarch64.toml
├── scripts/
│   └── test.sh           # Multi-arch run + expected log line checks
├── src/
│   └── main.rs           # Application entry point (HashMap memory test)
├── xtask/
│   └── src/
│       └── main.rs       # build/run and QEMU wiring
├── build.rs              # Linker script path (arch auto-detect)
├── Cargo.toml            # Package arceos-hashmap, axstd, etc.
├── rust-toolchain.toml   # Nightly, targets, llvm-tools
└── README.md

Key Components

Component	Role
axstd	ArceOS standard library (replaces Rust's std in no_std environment)
axhal	Hardware abstraction layer, generates the linker script at build time
build.rs	Locates the linker script generated by axhal and passes it to the linker
configs/*.toml	Pre-generated platform configuration for each architecture

License

GPL-3.0