# Reservoir Gods Atari Toolchain — Complete Technical Reference (llms-full)

> Exhaustive specification and technical reference for the Reservoir Gods modern 680x0 and Motorola DSP56001 cross-development suite (`rg-dis` and `rg-asm`), targeting Atari ST, TT, and Falcon computers.

---

## 1. System Overview & Core Philosophy

The Reservoir Gods toolchain provides modern, native, high-performance cross-development and reverse-engineering tools written in Rust, running on macOS, Linux, and Windows.

### The Round-Trip Re-Assembly Invariant
In legacy reverse engineering, disassemblers typically produce lossy textual dumps that require manual fixing of relative offsets, data tables, and syntax before they can be compiled. 
`rg-dis` and `rg-asm` are designed with **byte-exact round-trip fidelity**:
```text
Original Binary (.PRG) ──[ rg-dis ]──> Assembly Source (.s) ──[ rg-asm ]──> Rebuilt Binary (.PRG)
                               │                                              ▲
                               └─────────── Byte-for-Byte Match ──────────────┘
```
Any standard Atari executable disassembled by `rg-dis` re-assembles through `rg-asm` into a binary identical byte-for-byte to the original input.

---

## 2. Tool Reference: rg-dis

`rg-dis` is an intelligent disassembler for Motorola 680x0 and Motorola DSP56001 binaries, disk images, and containers.

### Core CLI Options & Grammar

```text
rg-dis [OPTIONS] [FILE]
```

- **Output Destination**:
  - `-o FILE`, `--output FILE`: Output file path. If omitted, disassembly writes to `stdout`.
- **Target Architecture**:
  - `--arch <ARCH>`: Target processor. Choices: `auto` (default, autodetects 68000/DSP), `68000`, `68010`, `68020`, `68030`, `68040`, `68060`, `dsp` (Motorola DSP56001).
- **Inspection & Analysis Modes**:
  - `--inspect[=VIEW]`: Generates a structured metadata report instead of assembly source.
    - Default view: `summary` (header flags, program segment sizes, symbol count, relocation count).
    - Other views: `header`, `sections`, `symbols`, `relocs`, `calls`, `traps`, `dsp`, `all`.
  - `--normalise` (alias `--normalize`): Generates a symbol-relative, layout-invariant listing for A/B diffing across builds.
  - `--json`: Formats all output (disassembly, inspection, metrics) as machine-readable JSON.
- **Cycle & Trap Annotations**:
  - `--annotate-cycles`: Annotates each instruction with dynamically computed 68000/68030 cycle timings in an aligned right column.
  - `--no-annotate-cycles`: Disables instruction cycle comments.
  - `--annotate-traps`: Decodes OS trap vectors (GEMDOS, BIOS, XBIOS, Line-A) with function names and stacked parameter signatures.
  - `--annotate-hw`: Decodes absolute memory accesses into symbolic Atari hardware registers (e.g., `$FFFF8201` -> `v_bas_h`).
- **Input Sources & Containers**:
  - `FILE`: Direct executable path (`.PRG`, `.TOS`, `.TTP`, `.BIN`, `.LOD`, `.P56`).
  - `--hex <HEXSTRING>`: Disassemble a raw hexadecimal byte string directly without creating a file.
  - `--container <FILE>`: Extract and disassemble directly from inside `.ZIP`, `.LZH`, `.ST`, or `.MSA` archives.
- **Display & Formatting**:
  - `-q`, `--quiet`: Suppress startup banner, progress messages, and autodetect notices.
  - `--ascii`: Draw inspection tables using standard ASCII characters instead of Unicode box-drawing characters.

### Disassembly Capabilities

1. **Control-Flow Analysis**:
   - Reconstructs multi-way jump tables (`jmp (pc,d0.w)` and `move.w (a0,d0.w*2),d1 / jmp (a0,d1.w)`).
   - Identifies switch/case blocks and branch target labels automatically.
   - Distinguishes code, jump tables, string tables, and inline data vectors.
2. **Motorola DSP56001 Extraction**:
   - Detects Falcon Host Interface data transfer sequences writing to `$FFFF8743` (Transmit High/Mid/Low bytes).
   - Extracts embedded DSP microkernels and writes them as standalone, annotated DSP56001 assembly files (`.asm`).
3. **Floppy Disk Image Inspection**:
   - Direct parsing of `.ST`, `.MSA`, and Pasti `.STX` sector containers.
   - Inspects executable boot blocks, root directories, and FAT12 filesystem layouts without operating system loopback mounts.

---

## 3. Tool Reference: rg-asm

`rg-asm` is a multi-dialect macro assembler for Motorola 680x0 and DSP56001.

### Core CLI Options & Grammar

```text
rg-asm [OPTIONS] [INPUTS]...
```

- **Output Destination**:
  - `-o FILE`, `--output=FILE`: Output file path.
- **Output Formats** (Mutually exclusive; default `--prg`):
  - `--prg`: Produce an Atari GEMDOS executable with standard 28-byte PRG header and relocation table (default).
  - `--obj[=KIND]`: Produce a linkable object file. Optional formats: `elf`, `dri`, `gst`, `coff`.
  - `--raw`: Produce a flat binary image (`.BIN`) without headers, symbols, or relocations.
  - `--reloc`: (Requires `--raw`) Appends a GenPC/OVR relocation table to the flat binary.
  - `--strip-bss`: (Requires `--raw`) Strips trailing zero bytes from flat output.
- **Processor Target**:
  - `-m CPU`, `--cpu=CPU`: Target CPU. Options: `68000` (default), `68010`, `68020`, `68030`, `68040`, `68060`.
- **Dialect Presets**:
  - `--dialect=DIALECT`: Selects syntax compatibility preset.
- **Listing & Diagnostics**:
  - `--listing[=FILE]`: Generates an annotated listing with assembled hex bytes and cycle timings.
  - `--no-emit`: Assembles and validates the source without writing an output binary artifact.
- **Language Server Protocol**:
  - `--lsp`: Runs the integrated Language Server Protocol (LSP) server over stdio for IDE integration (VS Code, Neovim, Helix).

### Supported Assembler Dialects

`rg-asm` provides high-fidelity syntax compatibility with major legacy assemblers:

| Dialect Key | Origin / Tool | Notable Syntax & Directive Features |
| :--- | :--- | :--- |
| `devpac` | HiSoft Devpac 1, 2 & 3 | `opt`, `section`, `incbin`, `include`, `rept`, `macro`, local labels starting with `.` |
| `vasm` | Volker Barthelmann's vasm | Standard modern Motorola syntax, `.macro`, `.include`, local labels starting with `.` |
| `rmac` | Subq / Subg RMAC | Modern Jaguar / Atari syntax, 68k + DSP unified directives |
| `seka` | K-Seka / Seka Assembler | Classical demoscene compact syntax, `=` symbol assignment, local labels |
| `purec` | Borland / Application Systems Pure C (PASM) | `GLOBL`, `EXPORT`, `IMPORT`, Pascal-style labels, fastcall ABI parameter passing |
| `gas` | GNU Assembler | AT&T or Motorola syntax, `.globl`, `.text`, `.data`, `.bss`, `.byte`, `.word`, `.long` |
| `mri` | Motorola Real-Time Interface | Industry standard Motorola manual syntax |
| `madmac` | Atari MadMac | Atari internal system development syntax, `.globl`, macro parameter indexing |
| `turboass` | TurboAss (ST demoscene) | TurboAss compact syntax rules and demoscene macro idioms |
| `sozobon` | Sozobon C as68 | Classical free C compiler assembly output syntax |

### Mixed-Mode Dual-Architecture Assembly
`rg-asm` uniquely supports writing Motorola 680x0 host code and Motorola DSP56001 code within the same project:
- Cross-architecture symbol resolution: 68k code can reference DSP memory addresses, and DSP code can reference host buffer offsets.
- Automatic binary packing: Assembled DSP programs can be embedded directly into GEMDOS DATA/BSS sections with automatic relocation.

---

## 4. Hardware Reference & Memory Maps

`rg-dis` and `rg-asm` contain built-in symbol dictionaries for standard Atari ST, STE, TT, and Falcon hardware registers and OS vectors:

### Hardware Register Address Space ($FFFF8000 – $FFFFFFFF)

- **Video & Shifter (ST / STE / TT / Falcon)**:
  - `$FFFF8201` (`v_bas_h`): Video Base Address High byte
  - `$FFFF8203` (`v_bas_m`): Video Base Address Mid byte
  - `$FFFF8205` (`v_bas_l`): Video Base Address Low byte (STE/Falcon)
  - `$FFFF8207` (`v_bas_vl`): Video Base Address Very Low byte (Falcon VIDEL)
  - `$FFFF8209` (`v_count_h`): Video Display Counter High byte
  - `$FFFF820A` (`v_syncmode`): Sync Mode (50 Hz / 60 Hz / External)
  - `$FFFF8240`–`$FFFF825E`: Shifter 16-colour palette registers (ST/STE)
- **Atari Blitter ($FFFF8A00 – $FFFF8A3F)**:
  - `$FFFF8A00` (`b_halftone`): 16 words of Halftone RAM ($FFFF8A00–$FFFF8A1E)
  - `$FFFF8A20` (`b_src_x_inc`): Source X increment
  - `$FFFF8A22` (`b_src_y_inc`): Source Y increment
  - `$FFFF8A24` (`b_src_addr`): Source address pointer
  - `$FFFF8A28` (`b_endmask1`): Endmask 1 (first word)
  - `$FFFF8A2A` (`b_endmask2`): Endmask 2 (middle words)
  - `$FFFF8A2C` (`b_endmask3`): Endmask 3 (last word)
  - `$FFFF8A2E` (`b_dst_x_inc`): Destination X increment
  - `$FFFF8A30` (`b_dst_y_inc`): Destination Y increment
  - `$FFFF8A32` (`b_dst_addr`): Destination address pointer
  - `$FFFF8A36` (`b_x_count`): X word count
  - `$FFFF8A38` (`b_y_count`): Y line count
  - `$FFFF8A3A` (`b_hop`): Halftone operation
  - `$FFFF8A3C` (`b_op`): Logical operation (0–15)
  - `$FFFF8A3D` (`b_ctrl`): Control byte (Start, Restart, Busy status)
  - `$FFFF8A3E` (`b_skew`): Skew byte (FXSR, NFSR, skew amount 0–15)
- **Motorola DSP56001 Falcon Host Interface ($FFFF8740 – $FFFF8747)**:
  - `$FFFF8741` (`dsp_icr`): Interface Control Register
  - `$FFFF8742` (`dsp_cvr`): Command Vector Register
  - `$FFFF8743` (`dsp_isr`): Interface Status Register
  - `$FFFF8744` (`dsp_ivr`): Interrupt Vector Register
  - `$FFFF8745` (`dsp_data_h`): Receive/Transmit High Byte
  - `$FFFF8746` (`dsp_data_m`): Receive/Transmit Mid Byte
  - `$FFFF8747` (`dsp_data_l`): Receive/Transmit Low Byte
- **Sound Subsystem**:
  - `$FFFF8800` (`ym_select`): YM2149 PSG register select / Read data
  - `$FFFF8802` (`ym_write`): YM2149 PSG register write data
  - `$FFFF8900` (`dma_sound_ctrl`): STE/Falcon DMA Sound control register
  - `$FFFF8901` (`dma_sound_frame`): Frame control register
  - `$FFFF8920` (`crossbar_src`): Falcon Sound Matrix crossbar source register
  - `$FFFF8922` (`crossbar_dst`): Falcon Sound Matrix crossbar destination register
- **MFP 68901 Multi-Function Peripheral ($FFFFFA00 – $FFFFFA3F)**:
  - `$FFFFFA01` (`mfp_gpip`): General Purpose I/O Port
  - `$FFFFFA03` (`mfp_aer`): Active Edge Register
  - `$FFFFFA05` (`mfp_ddr`): Data Direction Register
  - `$FFFFFA07` (`mfp_iera`): Interrupt Enable A (Timers, DMA, ACSI)
  - `$FFFFFA09` (`mfp_ierb`): Interrupt Enable B (Keyboard, MIDI, FDC)
  - `$FFFFFA13` (`mfp_imra`): Interrupt Mask A
  - `$FFFFFA15` (`mfp_imrb`): Interrupt Mask B
  - `$FFFFFA1F` (`mfp_tacr`): Timer A Control Register
  - `$FFFFFA21` (`mfp_tbcr`): Timer B Control Register

### Operating System Trap Decoders
`rg-dis` automatically annotates trap invocations:
- `trap #1`: GEMDOS (File I/O, process management, memory allocation)
- `trap #2`: GEM (VDI graphics and AES GUI calls)
- `trap #13`: BIOS (Character I/O, disk sector operations)
- `trap #14`: XBIOS (Hardware setup, video resolution, sound crossbar, MFP configuration)
- `dc.w $A000`–`$A00F`: Line-A fast low-level graphics primitives

---

## 5. Workflows & Recipes

### Workflow 1: Reverse-Engineering an Atari ST Game Binary
```bash
# 1. Disassemble the executable to structured source
rg-dis Dungeon.prg -o Dungeon.s

# 2. Re-assemble with rg-asm
rg-asm Dungeon.s -o TestDungeon.prg

# 3. Verify byte-exact identity
cmp Dungeon.prg TestDungeon.prg
# (Exits with 0 if perfectly byte-identical)
```

### Workflow 2: Extracting Falcon DSP Microkernels from a 68k Demo
```bash
# Disassemble the demo PRG. rg-dis automatically identifies transfers to
# the DSP Host Interface ($FFFF8743) and writes extracted DSP code.
rg-dis demo.prg -o demo.s

# Inspect the DSP algorithms independently:
rg-dis --arch dsp demo_dsp0.p56 -o demo_dsp0.asm
```

### Workflow 3: Modernising Legacy Devpac 3 Code
```bash
# Assemble legacy Devpac source directly on macOS or Linux without Wine:
rg-asm --dialect=devpac legacy_code.s -o modern_build.prg

# Generate an annotated cycle listing to identify execution bottlenecks:
rg-asm --dialect=devpac legacy_code.s --listing=listing.txt
```

### Workflow 4: Inspecting Floppy Images
```bash
# Inspect the partition/FAT structure and files inside an Atari floppy image:
rg-dis --inspect game_disk.st

# Disassemble a specific binary directly from inside the floppy disk container:
rg-dis --container game_disk.st AUTO/START.PRG -o start.s
```

---

## 6. Installation & Direct Downloads

Universal automated installer:
```bash
curl -sSL https://storage.googleapis.com/rg-tools-public/install.sh | sh
```

Direct standalone binaries are distributed via Google Cloud Storage:
- **Manifests & Metadata**:
  - `rg-dis`: `https://storage.googleapis.com/rg-tools-public/tools/rg-dis/latest.json`
  - `rg-asm`: `https://storage.googleapis.com/rg-tools-public/tools/rg-asm/latest.json`
- **Supported Architectures**:
  - `linux-x64`: Standard Linux x86_64 distributions
  - `linux-arm64`: AArch64 / Raspberry Pi / ARM Linux
  - `macos-arm64`: Apple Silicon (M1, M2, M3, M4) macOS
  - `macos-x64`: Intel x86_64 macOS
  - `windows-x64`: Modern 64-bit Windows 10/11
  - `windows7-x64` / `windows7-x86`: Legacy retro maintenance Windows systems

---

## 7. Links & Official Resources

- **Website**: https://rg.atari.org/
- **rg-dis Documentation**: https://rg.atari.org/tools/rg-dis/readme.html
- **rg-asm Documentation**: https://rg.atari.org/tools/rg-asm/readme.html
- **Dialect Guide**: https://rg.atari.org/tools/rg-asm/dialects.html
- **Output Formats**: https://rg.atari.org/tools/rg-asm/outputs.html
- **Compact Summary for AI Context**: https://rg.atari.org/llms.txt