arceos-altalloc

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

Method 2: Clone the tg-arceos-tutorial repository

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

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