Bellatrix

An AI-generated project, inspired by Bloodline's Omega.

The goal is AROS running at a usable speed on a Raspberry Pi 3 — which is where it is built and tested, not a limit of the idea. Nothing in the approach is specific to this board, and a stronger one, a Radxa Orion O6 say, would have more room than the Pi ever will.

AROS/m68k on a Raspberry Pi 3, with no Amiga anywhere in it.

Nothing here emulates a machine. There is no chipset, no Paula, Agnus or Denise, no simulated device and no timing model. M68K is treated as one more instruction set the board can run: Emu68 translates it to AArch64 as it executes, and the code works against real RAM and the Pi's own peripherals — closer to what Rosetta does for x86 on Apple silicon than to what UAE does for an Amiga.

Classic chipset compatibility is wanted later, through Rigel, for the software that needs Paula and friends to exist. It would sit beside this path rather than under it: native Pi hardware reached through m68k drivers, classic hardware semantics through Rigel, kept as separate domains.

Emu68 owns the bare metal and hands control to AROS once the hardware is up. Both are upstream projects, vendored as submodules and never edited in place.

Quick start

On Debian or Ubuntu, install what the build needs:

sudo apt-get install -y gcc-aarch64-linux-gnu cmake flex bison gperf \
    gawk netpbm libpng-dev liblzma-dev python3 python3-mako mtools \
    qemu-system-arm

Then:

git clone --recurse-submodules [email protected]:JJDSNT/bellatrix.git
cd bellatrix

./scripts/setup.sh          # check out the submodules, apply the patch series
./scripts/build.sh          # Emu68        → out/images/Emu68.img
./scripts/build-aros.sh full # AROS m68k + distribution tree
./scripts/make-sdcard.sh    # boot media   → out/aros/sd.img
./run.sh                    # boot the lot under QEMU

The Pi-oriented distribution can contain onboard devices that QEMU does not emulate. In particular, loading h4bthci.device blocks the startup while it waits for the Pi's BCM43438 Bluetooth controller. See the QEMU SD-card recipe for the currently validated staging step and the exact boot command.

Rigel, the classic Amiga chipset, is built in by default:

./scripts/build.sh              # with the chipset  → out/images/Bellatrix.img
CONFIG_RIGEL=0 ./scripts/build.sh  # without it     → out/images/Emu68.img

The build names the resulting composition explicitly, and the run, SD-card, timing, and release scripts select the name recorded by the last successful build. With CONFIG_RIGEL=0 Rigel is neither initialised by setup nor included in the Emu68 build; that composition is still supported, and switching the option in the same incremental build directory works.

Whether an image that carries the chipset actually uses it is a boot argument, not a build option. rigel on the kernel command line — the single line in cmdline.txt on the card — builds the classic machine: the low 24 bits belong to Paula, Denise and the CIAs, chip memory becomes a pool of its own, and two more cores are handed out. Leave the word off and the same files boot the chipset-less machine. Both halves read it, Emu68 for the address map and AROS for its memory layout, and both say which one they got on the serial line.

rigel                      # cmdline.txt: classic chipset
                           # cmdline.txt empty: no chipset, same card

The line is the authority: without the word there is no chipset, whatever the image carries. It cannot go the other way -- ask for rigel on an image built with CONFIG_RIGEL=0 and the machine says so and strikes the word out of the command line it hands to AROS, so both halves stay in agreement.

BELLATRIX_RIGEL=0 or =1 sets it for ./run.sh and ./scripts/make-sdcard.sh; without it they follow whatever the last build put in the image.

Chipset time comes from the wall clock, which a Pi 3 can keep and QEMU cannot: under emulation the chipset delivers about a fifth of the colour clocks a second of real time asks for, and the rest are discarded while its core stays pinned and holds the lock every CPU access to the classic domain waits on. bellatrix.chipdiv=N runs that clock at 1/N of real time instead, so the machine asks for what the host can actually give. It changes only the rate; what a colour clock does, and what it costs, is unchanged. Leave it out on hardware. ./run.sh is the QEMU path and nothing else, so it defaults the divisor to 8 with the chipset on rather than leaving a boot that does not work and a knob nobody knew to reach for; BELLATRIX_CHIPDIV=1 restores hardware's own behaviour there. To pick a value for another host, divide 3546895 by the CCK/s the [BELLATRIX:RIGEL:PERF] line reports and round up. A card is unaffected: make-sdcard.sh writes what you ask it for, and a release writes no divisor and no rigel at all.

Once the chipset core keeps up with its clock it starts paying a full step into Rigel for a handful of colour clocks at a time. bellatrix.chipfloor (BELLATRIX_CHIPFLOOR=1) holds a step back until it is long enough to reach the next thing the chipset can observe, which is a step that could not have produced an event anyway: measured at chipdiv=8, twenty times fewer calls for the same colour clocks, 17% off the cost of each one, and thirteen points of a core given back. It is off by default because the beam registers are not a deadline -- with it on, a CPU polling VPOSR with nothing else programmed reads a position up to two scanlines stale.

With Rigel enabled, src/machine/ remains the memory-policy control plane: it marks the coarse CIA, RTC, and custom-chip apertures as external in the same table that programs the Emu68 MMU. src/amiga/bus.c is the thin provider, and Rigel itself decodes the complete M68K-visible address and owns all classic hardware semantics.

Set aside a few hours for the first ./scripts/build-aros.sh: it builds an m68k cross toolchain from source before it can build AROS itself, and that takes longer than everything else combined. Later runs reuse it.

run.sh boots whatever is built: AROS if its ELF is there, otherwise Emu68 on its own. --no-aros forces the latter, --headless drops the window.

Trying it without a Pi

Every release carries bellatrix-<version>-qemu.tar.xz, which is the same system packaged to run under QEMU. Download it from Releases, unpack it anywhere, and:

./run.sh          # run.bat on Windows

That is all, given qemu-system-aarch64 — Debian and Ubuntu ship it as qemu-system-arm, and Windows users want the installer from qemu.weilnetz.de. Ctrl-A X quits, and ./run.sh -display none runs it on the serial line alone.

Running on a Raspberry Pi 3

You need a Pi 3 (Model B or B+), a microSD card of 2 GB or more, an HDMI monitor and a wired USB mouse. Everything else is built here.

Bellatrix boots the way any Emu68 setup does. Emu68 is the Pi's kernel, loaded by the firmware from the kernel= line of config.txt, and the m68k system it starts is handed to it as the initramfs — the slot where an Emu68 user names a Kickstart ROM:

kernel=Bellatrix.img.gz   # Rigel build; Emu68.img.gz without Rigel
arm_64bit=1
initramfs aros-emu68-m68k.elf

cmdline.txt beside it is the kernel command line, one line, and it is where the classic chipset is switched on and off — see rigel above.

Here that file is AROS, so there is no system image to write: the card holds ordinary files on a partition you formatted yourself, and config.txt says which of them boot.

The m68k system and the volume it boots from are separate choices. This card carries the AROS one, but neither half has to be ours — the objective is a volume that can just as well be an AmigaOS install, running on AROS as the resident system. docs/Compat.md is where that is written down.

1. Build

./scripts/build.sh              # Emu68
./scripts/build-aros.sh full    # AROS, complete — the plain build is not enough

2. Prepare the card

The card uses the Emu68 layout: MBR, and the first partition formatted FAT32. Nothing else is required of it, and its size is yours to choose — use the whole card if you want to.

3. Pack and unpack

./scripts/make-sdcard.sh --pack     # → out/aros/bellatrix-pi3.tar.xz

Unpack it at the root of that partition, with /media/you/BOOT replaced by wherever the card is mounted:

tar -xJf out/aros/bellatrix-pi3.tar.xz -C /media/you/BOOT

That is everything the Pi reads at power-on — firmware, Emu68, AROS and the settings — alongside the AROS system files.

4. Boot it

Insert the card, connect the monitor and the mouse, and power up. The loading screen appears first, then the Workbench desktop.

If it does not come up

The boot stops on the loading screen. Some USB devices stop it there. Power off, unplug everything from USB, and boot again; add the mouse back once you know the machine comes up. A plain wired mouse is the safe choice.

Nothing at all on the monitor. The green LED next to the card slot says how far the Pi itself got. If it never blinks, the card was not read at all — check that the first partition is FAT32, and try another card or another reader. Four or seven blinks mean files are missing from it: unpack the archive again, at the root of that partition.

A black screen with the LED behaving normally. Turn the monitor on before powering the Pi. If it stays black, add the line hdmi_force_hotplug=1 to config.txt on the card — that makes the Pi drive the output even when it cannot detect the monitor at power-on.

What works today

The Pi boots to the Workbench desktop. USB input is still being brought up, so some devices are not usable yet.

Layout

external/emu68      submodule → michalsc/Emu68            (pinned 9b4379a)
external/aros       submodule → aros-development-team/AROS (pinned 9757529)
external/aros-contrib submodule → aros-development-team/contrib
external/rigel      submodule → JJDSNT/Rigel (optional)

aros/arch/m68k-emu68  the AROS port — our source, symlinked into the AROS tree
aros/contrib/Demo/GL selected MesaGL examples → external/aros-contrib
aros/contrib/gfx/libs/glut GLUT link library → external/aros-contrib
patches/emu68/       10 patches on Emu68
patches/aros/        34 patches on AROS

scripts/            setup, build, build-aros, make-sdcard
run.sh              boot under QEMU (Emu68, or Emu68 + AROS + SD card)
out/                everything generated (git-ignored)

docs/               reference documentation
AI_context/         issues and consolidated knowledge

How upstream is modified

Two mechanisms, chosen by what the change is:

Patches, for changing code that belongs to someone else. Both series are cut by purpose — 7 patches on Emu68 (+304/−25 across 4 files), 22 on AROS (+608/−66 across 26 files). scripts/setup.sh applies them, and checks the result by a tree hash derived from the patches themselves, which is also what keeps the series honest: a patch that only undoes an earlier one shows up as changing nothing.

Symlinks, for shipping our own. The port under aros/arch/m68k-emu68 is 45 source files and ~5400 lines; as a patch it would be an unreviewable diff with no history of its own. It lives here as ordinary source and is linked into external/aros/arch/m68k-emu68, so there is exactly one copy and editing it from either path is the same file.

An applied series does not appear in git status, at either level — that is deliberate, since it is the normal working state. Use ./scripts/setup.sh --verify rather than git status to ask whether a submodule is as expected; it reads the working tree through a scratch index and reports pristine, applied, dirty or broken.

Documentation

docs/Compat.md	the compatibility objective: AROS as the resident system, with AROS and both families of AmigaOS userland booting on it, no Kickstart ROM required
docs/emu68.md	what the Emu68 patches change, where, and which patch each change comes from
docs/aros.md	the same for AROS, plus building and running
docs/irq.md	how a host interrupt becomes an m68k interrupt, and the three mechanisms available for it
patches/README.md	the patch and injection conventions
AI_context/	open issues and consolidated knowledge
AROS HEAD update roadmap	audited upstream changes, Bellatrix contribution provenance, patch reconciliation and validation required to update the AROS submodule

Nothing in either patch series is specific to this project — all of it is a candidate for upstreaming. Two of them are ordinary upstream bugs that this work happened to expose, and neither mentions this port: sdcard missing a NEWLIST before AddHead() writes through a NULL lh_Head (address 4, which on m68k is AbsExecBase), and a synchronous System() that never replies its startup packet, leaving the caller in WaitPkt() forever.

Status

Working, on a Raspberry Pi 3 Model B and under QEMU alike:

• the machine boots to the Workbench desktop;
• the SD card is the system volume — AROS runs from the same card it booted from;
• the display comes up on HDMI, and a wired USB mouse drives the desktop.

Still being brought up:

• USB input. Some devices stop the boot before the desktop appears; the machine has to be started without them, and a plain wired mouse is the safe choice. Which devices, and why, is what is being worked on now.
• Storage. The card is read correctly, but the driver stumbles once during start-up on real hardware and recovers by resetting the controller.
• The display path. nocomposition is no longer needed: the compositor that kept the screen from changing is gone from AROS, and the word is now ignored, so older cards that carry it still boot. Checked under QEMU; not yet on a Pi.

Fifty-five issues are filed under AI_context/issues/, with the grep recipes for querying them in AI_context/README.md.

Language

All content in this repository — documentation, issues, specs, code comments and commit messages — is written in English.

Acknowledgement

Special thanks to Claude for the guidance and support throughout the development of Bellatrix.

Credits

Bellatrix is the integration of two projects it does not own, and it would not exist without either:

• Emu68 by Michal Schulz — the M68K→AArch64 translator that makes m68k code run on the board at all;
• AROS — the operating system, and the m68k port this one descends from.

Both are vendored as submodules and used unmodified except for the patch series under patches/, all of which is written to be upstreamable.