Compatibility

Developing software for the Atari ST, TT, and Falcon meant choosing between a variety of incompatible assemblers; there was no single portable assembly specification. Code was written for whichever tool the author owned.

Each assembler made fundamentally different design choices. They diverged on arithmetic operator precedence (left-to-right versus standard algebraic precedence), macro parameter syntax (positional \1 versus named parameters), macro-local label generation (\@, \~), local label scoping (.name, 1234$, @@name, ?name), comment delimiters (*, ;, |), and structure definition directives.

As a result, legacy Atari source archives can be difficult to build. Discovering a historical source release rarely means you can build it out of the box. Usually you must make manual edits to get things working with a modern cross-assembler.

When we built rg-asm, our primary design goal was to eliminate this friction. Rather than inventing another proprietary syntax, rg-asm is built to ingest preserved Atari code exactly as it was originally written.

To measure compatibility against real-world code rather than artificial micro-benchmarks, we test rg-asm against the heritage corpus curated by ggn at ggnkua/Atari_ST_Sources. This collection holds over 17,000 assembly source files, written between 1985 and the present day by game makers, demoscene crews, utility authors, and Atari themselves.

We continually test changes to rg-asm against this corpus to ensure that we maintain compatibility with all these legacy dialects. This page tracks some of the concrete results of those tests.

Atari Assembler Differences

While several cross-assemblers and native tools target the 68000 family, their architectural priorities differ significantly. The table below compares rg-asm with the primary tools used in Atari development: vasm (with the Motorola syntax module), rmac (the modern MADMAC successor), and native Devpac 3 running on an Atari ST/Falcon (under Hatari).

Tier 1: Functional Ingestion

Functional ingestion tests whether historical source code compiles cleanly out of the box. The assembler must accept original syntax without manual edits, evaluate macros and dialect-specific expressions as intended, and emit valid executable or linkable binaries.

Tier 2: Binary Equivalence

Binary equivalence is a much stricter bar: does the emitted machine code match the original period binary byte-for-byte?

On the 68000, binary equivalence is vital for cycle-critical routines such as raster splits, border opening, and self-modifying code. If an assembler automatically shortens a 16-bit branch to an 8-bit branch, the altered cycle count breaks hardware timing.

What Binary Equivalence Requires

Matching original period binaries requires three factors to align:

1. Strict Instruction Sizing (--no-opt-size): Preserves explicit branch and addressing widths written by the author instead of automatically shortening them (e.g. bra.w → bra.s).
2. Isolating the Executable Payload: Strips volatile metadata (such as timestamps, host paths, or debugger symbols) to compare the true functional payload: TEXT, DATA, BSS size, and GEMDOS relocations.
3. Self-Contained Code: Fully resolved sources with no missing external symbols.

Dialect Quirks

Assembling legacy Atari source code without modifying files requires addressing six specific architectural hurdles that routinely break standard cross-assemblers:

1. Operator Precedence Divergence

One of the most insidious sources of silent assembly corruption is arithmetic operator precedence. In Pure C and Sozobon, expressions follow standard algebraic/C precedence, where multiplication binds tighter than addition and addition binds tighter than shifts:

val = 1 << 2 + 1 * 3   ; Pure C / Sozobon: evaluates to 32

In Devpac 1, 2, and 3, vasm, Alcyon AS68, Brainstorm, GST ASM, and Lattice C ASM, shifts bind tighter than multiplication, which in turn binds tighter than addition:

val = 1 << 2 + 1 * 3   ; Devpac / vasm / Alcyon / GST / Lattice: evaluates to 7

In Atari Corp MADMAC and rmac, expressions are evaluated strictly from left to right across all binary operators without operator weighting, as documented in Atari's official MADMAC User's Manual ("All binary operators have the same precedence: expressions are evaluated strictly left to right. Thus the expression 1+2*3 evaluates to 9, not 7"):

val = 1 << 2 + 1 * 3   ; MADMAC / rmac: evaluates to 15

If one dialect's precedence is applied to code written for another, table offsets and raster line counts quietly calculate wrong values without generating an error. rg-asm addresses this by assigning specific precedence models per dialect. The shift-binding model (Devpac, vasm, Alcyon, GST, Lattice) and left-to-right model (MADMAC, RMAC) have been empirically verified by executing authentic period assembler binaries under godbox emulation and cross-referencing their official reference manuals. Dialects without an authentic host oracle currently retain an interim C-precedence model pending direct binary verification.

2. Macro Parameter Syntax & Variable Arguments

Different assemblers implemented distinct macro engines:

• Positional Arguments: Devpac uses \1 through \9; MADMAC supports \1..\9 alongside \# (argument count) and string concatenation.
• Local Label Generation: Devpac uses \@ to insert a unique invocation index; PhxAss and Devpac 3 support @@ and \@; MADMAC uses \~ and ?0; vasm-mot handles nested macro stacks.
• Named Parameters: GNU as (GAS), RMAC, and Metacomco support named parameters rather than numbered arguments.

rg-asm implements a multi-model macro expander capable of evaluating positional substitution, named parameter binding, repetition directives (REPT/ENDR and .rept/.endr), and conditional macro checks (IFMACROD, ^^defined) without syntax rejection.

3. Filesystem Conventions & Path Normalisation

Historical Atari source code was developed on GEMDOS/FAT12 filesystems, which were strictly case-insensitive and used backslashes (\) as directory separators:

    INCLUDE "INCLUDES\SYS_VAR.I"
    INCBIN  "DATA\SPRITES.DAT"

On modern POSIX host systems (Linux and macOS), these paths fail immediately because filesystems are case-sensitive and treat \ as an escape character rather than a path separator. rg-asm incorporates transparent path normalisation:

• Converts backslashes to forward slashes automatically.
• Performs case-insensitive directory and file lookups across host file trees.
• Maintains search path hierarchies passed via -I, matching original GEMDOS folder resolution.

4. Local Label Scoping Rules

Local labels allow subroutines to reuse common identifiers (such as loop labels). However, each era introduced a different local naming convention:

• Devpac 1, 2, and 3: Period-prefixed identifiers (.loop, .skip) and numeric locals (1$, 2$).
• Turbo Assembler: Double-at identifiers (@@loop, @@exit).
• MADMAC & rmac: Question-mark identifiers (?loop) and double-colon global scope breaks (::).
• GNU as / vasm gas: Numeric jump labels (1:, forward 1f, backward 1b).

rg-asm scopes local labels according to the dialect rules of the input file, clearing local symbol tables on global label transitions or section breaks exactly as expected by the original author.

5. Structure Offsets & Layout Directives

To define memory structures, developers used competing directive sets:

• Devpac 2 and 3: RSRESET, RS.B, RS.W, RS.L, and __RS counters.
• Metacomco / vasm: OFFSET, SO, and FO offset definitions.
• PhxAss / rmac: STRUCTURE and ENDS blocks.

rg-asm maintains native support for each layout pattern, allowing structural offsets to evaluate without manual conversion to constant equates.

6. Falcon 030 + Motorola DSP56001 Mixed-Mode Assembly

On the Atari Falcon 030, high-performance routines typically split work between the 16 MHz 68030 host CPU and the 32 MHz Motorola DSP56001 digital signal processor. Historically, assembling Falcon productions required running two completely separate assemblers: an m68k assembler for the host code and Motorola's asm56000 (or Brainstorm's b56) for the DSP microkernel, followed by a conversion script to turn the DSP binary into a .P56 file or inline DC.W data statements.

rg-asm natively supports both instruction sets in a single tool. Developers can switch architectures directly in source or assemble DSP kernels into standalone .LOD, .P56, .DSP, or raw binary formats without auxiliary tooling.

Instruction Widths & Branch Sizing

A common frustration when assembling historical 68000 code with modern compilers is binary drift caused by automated size optimisation.

When optimising for size, modern assemblers automatically:

• Shorten 16-bit word branches (bra.w label) to 8-bit short branches (bra.s label) if the displacement fits in −128 to +127 bytes.
• Convert absolute memory addressing (move.l $10000,d0) to PC-relative addressing (move.l label(pc),d0).
• Collapse zero-displacement address register offsets (0(a0) to (a0)).

While beneficial for general application code, automatic branch shortening can be catastrophic in time-critical Atari demoscene or game code. Sync scrolling, border-opening routines and some soundchip effects rely on exact instruction cycle timing. If an instruction is shortened from 12 cycles to 10 cycles (or 8 cycles for an untaken conditional branch), these effects will not work correctly.

Historical Sources

Below are some examples of classic Atari sources. In each case, rg-asm ingests the preserved source and compiles cleanly, while rival cross-assemblers often stumble over period-specific syntax, macro expansions, or local label rules:

Dialect Ingestion Comparison

Beyond individual productions, we executed each tool across our test suites covering twelve historical Atari assembler dialects. The table below records build success (without modifying source files), alongside the main issues causing tools to reject the code:

A Single Universal Assembler

Our design goal with rg-asm is to provide a single, universal assembler capable of building any Atari source code—past, present, or future. Instead of juggling fragmented toolchains, emulated environments, or bespoke syntax flags, developers have a tool that is simple to deploy and operate: distributed as a self-contained, native executable with zero external dependencies, supporting all modern host platforms.

Preserving this level of compatibility requires ongoing testing. As new features, optimisations, and bug fixes are delivered, rg-asm continues to be regression-tested against the full heritage corpus to ensure that existing legacy code builds reliably and without regressions.