# arceos-altalloc

A standalone [ArceOS](https://github.com/arceos-org/arceos) unikernel exercise (`arceos-altalloc`): implement a bump-style memory allocator, 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-system-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-altalloc crate from crates.io
cargo clone arceos-altalloc
# into crate dir
cd arceos-altalloc
```

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-altalloc
```

### 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 a new kernel memory allocator component named `bump_allocator`, which is based on the simple "bump" allocation algorithm.

The `axalloc` crate has already been modified locally (see `modules/axalloc`), and is selected in the root `Cargo.toml` via `[patch.crates-io]`, so the global allocator will use your `bump_allocator` implementation automatically.

You should implement the bump memory allocation algorithm mainly in `modules/bump_allocator`, and keep changes elsewhere to a minimum. Typically, you can finish the exercise by editing `bump_allocator` alone.

### Expectation

Serial output should include:

```
Running bump tests...
Bump tests run OK!
```

### Verification

- The serial output must contain **`Running bump tests...`**.
- The serial output must contain **`Bump tests run OK!`**.

Run the test script:

```bash
bash scripts/test.sh
```

### Tips

1. You can refer to the existing page allocator and byte allocator to implement the corresponding Traits..
2. This `bump_allocator` acts as both a byte allocator and a page allocator. Therefore, it must implement three Traits: `BaseAllocator`, `ByteAllocator`, and `PageAllocator` simultaneously. This is different from the existing references.

## Project Structure

```
exercise-altalloc/
├── .cargo/
│   └── config.toml
├── configs/
│   ├── riscv64.toml
│   ├── aarch64.toml
│   ├── x86_64.toml
│   └── loongarch64.toml
├── modules/
│   ├── bump_allocator/   # Exercise focus: EarlyAllocator + bump logic
│   └── axalloc/          # Vendored axalloc fork; selects bump as default (see its README)
├── scripts/
│   └── test.sh
├── src/
│   └── main.rs           # Large Vec + sort (stresses global allocator)
├── xtask/
│   └── src/main.rs
├── build.rs
├── Cargo.toml            # [patch.crates-io] axalloc -> modules/axalloc
├── rust-toolchain.toml
└── 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 |
| `bump_allocator` | Your bump / early allocator; implements `BaseAllocator`, `ByteAllocator`, `PageAllocator` |
| `axalloc` (local) | Global `#[global_allocator]`; exercise fork defaults to `bump_allocator` + `level-1` |
| `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
