arceos-hashmap 0.4.0

# arceos-hashmap

A standalone [ArceOS](https://github.com/arceos-org/arceos) unikernel exercise (`arceos-hashmap`): enable `collections::HashMap` under `axstd`, with dependencies from [crates.io](https://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)

  ```bash
  rustup install nightly
  rustup default nightly
  ```

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

  ```bash
  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)

  ```bash
  # 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)

  ```bash
  cargo install cargo-binutils
  rustup component add llvm-tools
  ```

## Quick Start

### Get Source Code

Method 1: Get source code from crates.io

```bash
# 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

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

### Build & Run

```bash
# 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
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`:

```bash
cargo clone axstd@0.3.0-preview.1
```

```toml
[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