# Reservoir Gods Atari Toolchain

> High-performance cross-development and reverse-engineering toolchain for Motorola 680x0 and DSP56001 systems (Atari ST, TT, Falcon 030), running natively on macOS, Linux, and Windows.

Modern 680x0 and Motorola DSP56001 toolchain developed in Rust by Reservoir Gods. Engineered for cross-platform development, retro preservation, reverse engineering, and demoscene production with byte-exact round-trip verification.

## Core Capabilities & Unique Selling Points

- **Byte-Identical Round-Trip Re-Assembly**: `rg-dis` recovers structured assembly source code that re-assembles byte-for-byte to the original binary via `rg-asm`, eliminating manual fixup of data tables, branch offsets, and instruction boundaries.
- **Motorola DSP56001 Support**: Full unified assembler and disassembler for Falcon DSP binaries, with automatic detection and extraction of embedded DSP microkernels uploaded through the Atari Falcon Host Interface ($FFFF8743).
- **Instruction Cycle Annotations**: Automatically calculates instruction execution cycles dynamically for Motorola 68000 and 68030 processors, annotating listings per line and exporting function-level cycle rollups.
- **OS Trap & Hardware Register Annotations**: Automatic trap call decoding for GEMDOS, BIOS, XBIOS, Line-A, AES, and VDI with function names and stack arguments, plus symbolic recognition of Atari hardware registers (MFP 68901, Blitter, VIDEL, YM2149 PSG).
- **Containers & Floppy Disk Images**: Direct inspection and extraction of `.ST`, `.MSA`, and Pasti `.STX` floppy disk images, boot sectors, and `.ZIP`/`.LZH` archives without mounting or uncompressing.
- **Native Host Support**: Pre-compiled, self-contained native binaries for macOS (Apple Silicon arm64 & Intel x64), Linux (x86_64 & aarch64), and Windows (x64 & legacy Windows 7 x86/x64).

## Core Tools

### rg-dis
Intelligent 680x0 and Motorola DSP56001 disassembler with round-trip fidelity to `rg-asm`.
- Control flow and data analysis: Automatic jump table discovery, symbol recovery, switch/case decoding, exception vector identification, and instruction vs. inline data classification.
- Embedded DSP transfer recovery: Reconstructs DSP56001 algorithms uploaded via the Falcon Host Interface into separate, annotated DSP assembly files.
- Signature detection: Recognises Pure C runtime startup code, standard library routines, and GEM/VDI/AES parameter blocks.
- Input formats: Atari PRG/TOS/TTP executables, DSP LOD/P56 binaries, floppy disk images (`.ST`, `.MSA`, `.STX`), boot sectors, raw binary dumps, and nested archives.
- Web & Docs: https://rg.atari.org/tools/rg-dis/ | https://rg.atari.org/tools/rg-dis/readme.html

### rg-asm
Universal macro assembler for Motorola 680x0 (68000 through 68060) and Motorola DSP56001.
- Native mixed-mode dual-architecture assembly: Combine 68k and DSP56001 instructions in the same source file; resolves symbols across boundaries and automatically bundles DSP binaries into the host executable.
- Universal dialect support: Assemble legacy code written for HiSoft Devpac 1/2/3, vasm, RMAC, Seka, Pure C / PASM, GNU as (GAS), Motorola MRI, MadMac, TurboAss, and Sozobon without manual rewriting.
- Output formats: Atari PRG/TOS executables, Falcon DSP LOD and P56 binaries, raw flat binaries (`.BIN`), boot sectors, GST/DRI linkable objects, and modern ELF/COFF objects.
- Integrated LSP: Built-in Language Server Protocol server (`--lsp`) over stdio for IDE integration.
- Web & Docs: https://rg.atari.org/tools/rg-asm/ | https://rg.atari.org/tools/rg-asm/dialects.html | https://rg.atari.org/tools/rg-asm/outputs.html

## Target Systems & Hardware

- **Processors**: Motorola MC68000, MC68010, MC68020, MC68030, MC68040, MC68060, Motorola DSP56001 (24-bit fixed-point, 32 MHz).
- **Atari Hardware**: Atari 520ST, 1040ST, Mega ST, STE, TT030, Falcon 030.
- **Peripherals & Subsystems**: YM2149 PSG, STE DMA sound, Falcon crossbar, VIDEL, Blitter, MFP 68901, Line-A, GEMDOS, BIOS, XBIOS.

## Quick CLI Recipes

Disassemble an Atari PRG to re-assemblable source:
```bash
rg-dis input.prg -o recovered.s
```

Assemble source to an Atari PRG executable (Devpac dialect):
```bash
rg-asm --dialect=devpac source.s -o program.prg
```

Verify round-trip byte-identical disassembly:
```bash
rg-dis original.prg -o temp.s
rg-asm temp.s -o rebuilt.prg
cmp original.prg rebuilt.prg
```

Disassemble an Atari Falcon DSP program:
```bash
rg-dis --arch dsp dspcode.p56 -o dsp_recovered.asm
```

Assemble dual-architecture 68k + Falcon DSP executable:
```bash
rg-asm --cpu=68030 source.s -o falcon_demo.prg
```

Inspect metadata and sections of an Atari binary or floppy image:
```bash
rg-dis --inspect game.st
```

Generate assembly listing with 68000 instruction cycle annotations:
```bash
rg-dis --annotate-cycles program.prg -o annotated.s
```

## Installation & Downloads

Automated universal installer (Linux, macOS, Windows Subsystem for Linux):
```bash
curl -sSL https://storage.googleapis.com/rg-tools-public/install.sh | sh
```

Direct binary downloads (standalone zero-dependency zip archives):
- **Linux x64**: https://storage.googleapis.com/rg-tools-public/tools/rg-dis/latest.json (via latest manifest)
- **Linux arm64**: Native Raspberry Pi / AArch64 builds available in the distribution bucket.
- **macOS Apple Silicon (M1/M2/M3/M4)**: Native ARM64 binaries for modern macOS.
- **macOS Intel (x64)**: Native x86_64 binaries for Intel Macs.
- **Windows x64**: Standalone 64-bit executables for Windows 10/11.
- **Windows 7 (x86/x64)**: Legacy builds supporting older retro maintenance machines.

## Extended Documentation

For complete CLI flags, dialect directive tables, OS trap call registers, and hardware memory maps, see:
- Full Technical Reference: https://rg.atari.org/llms-full.txt
- Tool Index: https://rg.atari.org/