Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 29 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Everything runs in the tools container (see docker/Dockerfile).
# Everything runs in the tools container (see docker/Dockerfile), except the
# onerom-* targets: they run the onerom CLI on the host, which owns the USB
# connection. See "Test setup: One ROM" in README.md.
# KICK (only needed for `make rom`) must be inside this directory, since only
# it is mounted.

Expand All @@ -9,12 +11,19 @@ COPIES ?= 1
# Set by the release workflow; mkrelease.sh refuses a tag that doesn't match
# the version in src/ppi2000mem.asm.
RELEASE_TAG ?=
# The One ROM header pin wired to the host's reset line.
ONEROM_RESET_PIN ?= sel_c
# The 512K, byte-swapped image `make onerom-poke` loads.
ONEROM_IMAGE ?= $(ROM).bin
# Names the default KICK's ROM, so a build from another KICK needs its own config.
ONEROM_CONFIG ?= tools/onerom-a2000.json

RUN := docker compose run --rm -T -e RELEASE_TAG=$(RELEASE_TAG) tools
VASM := vasmm68k_mot -Fhunkexe -nosym -quiet
PPS := vendor/pps040/files/PPS_040-24_2/PPI_040

.PHONY: help image fetch modules test disasm bootdisk rom release clean
.PHONY: help image fetch modules test disasm bootdisk rom release clean \
onerom-menu onerom-poke onerom-flash

help:
@echo "make image build the tools container"
Expand All @@ -26,6 +35,10 @@ help:
@echo "make rom patch KICK with the module into $(ROM).rom/.bin"
@echo " (COPIES=4 also writes -x4.bin for a 2 MB chip)"
@echo "make release package the binaries, mkrom.py and docs in build/release"
@echo "make onerom-menu restart the One ROM and reset the Amiga into the boot menu"
@echo "make onerom-poke load ONEROM_IMAGE into the One ROM's RAM and reset the Amiga"
@echo " (default $(ROM).bin; lost when the One ROM restarts)"
@echo "make onerom-flash build the ROM, flash ONEROM_CONFIG and reset the Amiga"

image:
docker compose build tools
Expand Down Expand Up @@ -61,5 +74,19 @@ rom: modules
release: modules test
$(RUN) tools/mkrelease.sh

onerom-menu:
onerom reboot && onerom control reset --pin $(ONEROM_RESET_PIN)

# Doesn't depend on rom, as ONEROM_IMAGE need not be our build: use
# `make rom onerom-poke` to load a fresh one.
onerom-poke:
@test -f "$(ONEROM_IMAGE)" || { echo "No image at $(ONEROM_IMAGE); run make rom or set ONEROM_IMAGE" >&2; exit 1; }
onerom poke --address 0 --input $(ONEROM_IMAGE) && onerom control reset --pin $(ONEROM_RESET_PIN)

# The pin must be reserved on every flash, or the firmware reads the reset line
# as an image select pin.
onerom-flash: rom
onerom program --config $(ONEROM_CONFIG) --reserve-pin $(ONEROM_RESET_PIN) --reset-host $(ONEROM_RESET_PIN)

clean:
rm -rf build
80 changes: 80 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ on this and learn more about assembly for the 68k.
| `tools/disasm.py` | disassembler for AmigaOS executables, used on the PP&S software |
| `tools/fetch.sh` | downloads the original PP&S driver disks |
| `tools/mkrelease.sh` | packages a release (zip and ADF) |
| `tools/onerom-a2000.json` | the One ROM slots for the [test setup](#test-setup-one-rom) |
| `tests/` | runs the module on an emulated 68040 against simulated cards, and mkrom.py against a synthetic Kickstart |
| `docs/hardware.md` | the card: jumpers, memory layout, measurements |
| `docs/reverse-engineering.md` | what the original driver does and how ppi2000mem differs |
Expand Down Expand Up @@ -87,6 +88,85 @@ artifact. To publish a release:
To read the original driver: `make disasm` downloads the PP&S disks into `vendor/` and writes
the listings to `build/disasm/`.

## Test setup: One ROM

The reference machine can test ROM builds on a [One ROM](https://onerom.org) Fire 40 Rev B in the
A2000's Kickstart socket instead of burning a chip. A new build can be running on the real card in
a few seconds, from the host and with the case closed. This is optional and nothing else in this
repository needs it.

```
make rom onerom-poke # build the ROM, load it into the One ROM's RAM, reset the Amiga
make onerom-menu # back to the boot menu
make onerom-flash # build the ROM, write all the slots to flash, reset the Amiga
make onerom-poke ONEROM_IMAGE=amiga_roms/onerom/diagrom-2.0-16bit.bin # any other 512K image
```

These targets run the [`onerom` CLI](https://onerom.org/cli) on the host rather than in the tools
container, because they need the USB connection. They expect the USB cable to be connected.

### Slots

`tools/onerom-a2000.json` holds what `make onerom-flash` writes. The board's 2 MB of flash fits
three 512K images alongside the firmware and plugins, so anything else, such as DiagROM, is loaded
with `make onerom-poke`.

| Slot | Image |
|------|---------------------------------------------------------------------|
| 0 | `amiga_roms/onerom/amiga_boot_512k_always_menu.bin`, the boot menu |
| 1 | `build/CDTVA500A600A2000.47.115-ppi2000mem.bin`, this project's ROM |
| 2 | `amiga_roms/CDTVA500A600A2000.47.115.bin`, stock 3.2.3 |

All the images are byte-swapped (`.bin`), and are git-ignored for the reasons
[below](#not-included). The boot menu is the
[RBCP Amiga bootloader](https://github.com/piersfinlayson/rom-bus-control-protocol/tree/main/reference/host/68k/amiga-boot)
built with `make ROM_KB=512 DEV=1`, which writes `build/amiga_boot_swapped.bin`. The stock build
only opens the menu if both mouse buttons read as held at the moment it checks, which never
happened on the reference machine. `DEV=1` always opens it. DiagROM's image is `16bit.bin` from
the [DiagROM](https://www.diagrom.com/) release.

### Reset wire

A wire from the One ROM's `SEL_C` pin to the 68000's reset line lets the host reset the Amiga, with
the 040 card fitted. The reference machine connects it at a via on the same net as the 68000's
pin 18. Check the pin with a meter before connecting it, because the holes
are easy to confuse. Reading the labels on the underside of the board, it is the lower hole in the
`C` column, directly above the `CLK` label:

```
SEL_A SEL_B BOOTSEL RUN 5V upper row of holes
A B C D 5V labels
GND GND [SEL_C] SEL_D GND lower row of holes
0=Open CLK DIO GND labels
```

`SEL_C` and `SEL_D` are 5V tolerant. **`SEL_A` and `SEL_B` are 3.3V only, so never connect them to
the reset line.** `onerom board header --board fire-40-b` draws the header from above.

`make onerom-flash` always passes `--reserve-pin`, which stops the firmware reading the wire as an
image select pin. Keep that option if you flash by hand. `SEL_C` is also the debug probe's clock,
so remove the wire to use a probe.

### What restarts what

The menu copies the chosen image over the one in the One ROM's RAM, including the menu itself,
and `make onerom-poke` does the same with its image. Only a restart of the One ROM brings the menu
back. A reset of the Amiga doesn't restart it, and with USB connected neither does switching the
Amiga off, because USB keeps the One ROM powered.

| Action | The Amiga then boots |
|------------------------------------------|-----------------------------|
| Ctrl-Amiga-Amiga, or the reset wire | the same image |
| Power cycle with USB connected | the same image |
| Power cycle with USB unplugged | the boot menu |
| `make onerom-menu` | the boot menu |

So a poked build survives a power cycle while USB is connected, which allows a true cold-start test
of the module.

Flashing, restarting or poking the One ROM changes the ROM under a running Amiga, so expect it to
crash until the reset that follows.

## Status

Burned and in daily use on one A2000 with a 32 MB card, with 0 MB and 2 MB of autoconfig RAM.
Expand Down
10 changes: 7 additions & 3 deletions docker/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,13 @@ RUN apt-get update \
&& rm -rf /var/lib/apt/lists/*
# Pinned: the tests depend on Unicorn's behaviour (see src/ppi2000mem.asm).
RUN pip install --no-cache-dir amitools==0.8.1 capstone==5.0.9 unicorn==2.1.4 pytest==9.1.1
# vasm (m68k, Motorola syntax). Only a "latest" archive is published, so the
# build prints the version it got.
RUN curl -sSL http://sun.hasenbraten.de/vasm/release/vasm.tar.gz | tar xz -C /tmp \
# vasm (m68k, Motorola syntax). Upstream only publishes a "latest" archive and
# its URL has moved before, so this is a pinned copy of the 2.0f release,
# checked against its hash.
RUN curl -fsSL -o /tmp/vasm.tar.gz https://github.com/piersfinlayson/one-rom-build-deps/releases/download/vasm-2.0f/vasm-2.0f.tar.gz \
&& echo "c84b2de1cbb87831795fe64a85c5d9a7002a766e3a7c30b0a2d7d5e99d878f49 /tmp/vasm.tar.gz" | sha256sum -c - \
&& tar xzf /tmp/vasm.tar.gz -C /tmp \
&& rm /tmp/vasm.tar.gz \
&& make -C /tmp/vasm CPU=m68k SYNTAX=mot \
&& cp /tmp/vasm/vasmm68k_mot /tmp/vasm/vobjdump /usr/local/bin/ \
&& rm -rf /tmp/vasm \
Expand Down
56 changes: 56 additions & 0 deletions tools/onerom-a2000.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
{
"$schema": "https://images.onerom.org/configs/schema.json",
"version": 1,
"name": "A2000 menu, custom, stock",
"description": "RBCP boot menu, Kickstart 3.2.3 with ppi2000mem, and stock Kickstart 3.2.3. Paths are relative to the repository root; see the One ROM test setup in README.md.",
"chip_sets": [
{
"type": "single",
"chips": [
{
"type": "system_plugin",
"plugin": "usb"
}
]
},
{
"type": "single",
"chips": [
{
"type": "user_plugin",
"plugin": "host-control"
}
]
},
{
"type": "single",
"chips": [
{
"label": "Bootloader",
"file": "amiga_roms/onerom/amiga_boot_512k_always_menu.bin",
"type": "27C400"
}
]
},
{
"type": "single",
"chips": [
{
"label": "Kickstart 3.2.3 PPS040",
"file": "build/CDTVA500A600A2000.47.115-ppi2000mem.bin",
"type": "27C400"
}
]
},
{
"type": "single",
"chips": [
{
"label": "Kickstart 3.2.3",
"file": "amiga_roms/CDTVA500A600A2000.47.115.bin",
"type": "27C400"
}
]
}
]
}
Loading