Axiom64

Axiom64 is a bare-metal Rust machine experiment aimed at "the next Amiga": custom-chip style graphics and input, direct hardware access, and a guest model that can grow toward a real machine rather than only a kernel demo.

Today it boots on:

• QEMU virt as the default development loop
• Raspberry Pi 3 / 3B+ as the first real hardware target

It is not trying to clone the Amiga register map or operating system exactly. The goal is to reuse the good architectural ideas:

• display hardware as a first-class subsystem
• copper/blitter/sprite style thinking
• raw device input plus higher-level libraries
• guest software that can bang hardware directly when needed

Current State

The project already has:

• a custom AArch64 reset path into Rust
• linker scripts and boot images for QEMU and Raspberry Pi 3
• UART console and shell
• framebuffer bring-up on QEMU and Raspberry Pi
• software graphics device model with:
  • chunky Xrgb8888
  • Indexed8
  • planar Bitplane1/2/4/8
• software blitter, tilemaps, palettes, sprite handles, and display surfaces
• timer IRQs and a software vblank timing model
• a custom-chip MMIO model and monitor commands
• guest-side scripting and tests
• host-side runners for guest scripts, tests, shell commands, and Lua-authored guest programs

This is still an early machine bring-up, not an OS in the traditional sense. There is no process model, filesystem, scheduler, protection, or resident GUI.

Project Direction

The medium-term direction is:

• richer chunky and planar graphics modes
• more explicit custom-chip register blocks
• sprite/object hardware model
• copper/display-list behavior
• better guest-facing tooling and scripting
• eventually memory protection and a more serious operating environment

The graphics direction is intentionally broader than a stock Amiga:

• planar modes remain important
• chunky modes are first-class too
• indexed and true-color workflows should both exist
• the "custom chips" should evolve rather than only emulate history

Workspace Layout

• kernel/ contains the bare-metal runtime, drivers, graphics, monitor, and guest-side script/test support
• xtask/ contains host-side build/run tooling
• guestlua/ contains host-side Lua guest-program experiments
• LICENSE contains the project license for original code
• THIRD_PARTY_NOTICES.md tracks third-party material used in the repo

Quick Start

Minimum toolchain:

• Rust with aarch64-unknown-none
• llvm-objcopy
• qemu-system-aarch64
• lua for the host-side Lua bridge

Common setup with rustup:

rustup target add aarch64-unknown-none

On macOS with Homebrew, install the host tools with:

brew install llvm qemu lua rustup

Then make sure the shell uses the rustup-managed Rust toolchain and Homebrew's LLVM tools first on PATH:

export PATH="$(dirname "$(rustup which cargo)"):/opt/homebrew/opt/llvm/bin:$PATH"

This matters if cargo or rustc currently resolve to Homebrew's standalone Rust formula. In that case rustup target add aarch64-unknown-none succeeds, but cargo xtask doctor and cross-builds still fail because the active sysroot does not include that target.

Check the environment:

cargo xtask doctor

Run QEMU in serial mode:

cargo xtask qemu

Expected headless boot banner:

Axiom64 booting on QEMU virt
display offline: fw_cfg etc/ramfb file is missing
UART online; entering shell.
> 

Run QEMU with framebuffer output:

cargo xtask qemu-gfx

Build a Raspberry Pi image:

cargo xtask image

Verified on this machine:

• cargo xtask doctor
• cargo xtask build
• cargo xtask image
• cargo xtask qemu

cargo xtask qemu-test all built successfully but the automated prompt wait timed out on this host; the interactive cargo xtask qemu boot reached the shell prompt.

Useful Commands

Host-side:

cargo xtask qemu-test all
cargo xtask qemu-script demo-bgcycle
cargo xtask qemu-lua demo-bgcycle
cargo xtask qemu-cmd "gfx planar-demo"

Guest-side shell:

help
chip info
chip map
gfx indexed-demo
gfx planar-demo
gfx tile-demo
gfx cycle-demo
test all
script list

Guest Programs

There are currently three layers for guest control:

1. direct monitor commands such as peek32 / poke32
2. the small built-in script/test DSL
3. host-side Lua that emits guest monitor/script statements

That Lua layer is intentionally a prototype. It is useful because it helps shape what a future resident guest language should feel like, but it is not yet "Lua running inside the machine."

Licensing

The project’s original code is released under the MIT license. See LICENSE.

This repository also includes a Topaz-compatible bitmap console font derived from AROS material. That font is not covered only by the top-level MIT license; see THIRD_PARTY_NOTICES.md and LICENSES/AROS-Public-License-1.1.txt.