GFA-BASIC Disassembly

GFA-BASIC was one of the most popular languages on the Atari ST, used for everything from GEM utilities and desktop tools to shareware games and demoscene intros. Because its compiler produced fast, compact 68000 executables, a huge share of classic Atari software is compiled GFA-BASIC.

Trying to read a raw disassembly of a compiled GFA program, though, is notoriously difficult. Rather than calling normal named subroutines or direct OS traps, GFA routes almost every command through cryptic negative offsets off A4 and A6 (JSR -$5E7A(A4)) and stores every variable as an anonymous negative offset off A5 (MOVE.L -$7E1C(A5),D0). Without knowing which GFA runtime table you're looking at, it's nearly impossible to tell a CLS or TEXT command from a PAUSE or a floating-point FOR loop.

rg-dis detects the GFA-BASIC runtime automatically, identifies the compiler version, and turns those opaque offsets back into named GFA commands, decoded arguments, and labelled variables.

Versions

Family Supported Runtime Versions
GFA-BASIC 2.x v2.00, v2.0F, v2.02, v2.50
GFA-BASIC 3.x v3.02, v3.50, v3.50F, v3.60, v3.6DE, v3.6TT, v3.6TTB

Variable Names

Accesses via A4 (GFA runtime workspace fields such as screen bases) and A5 (global variables) emit named equates and deduce variable names from referenced data strings. Within user procedures, references to the A6 frame pointer are annotated as well:

Before

    MOVE.L    $24(A4),D0
    MOVE.W    $50(A4),D1
    MOVE.L    -$7E1C(A5),D0

After

; Equates emitted in preamble:
; GFA_WS_SCREEN_LOGIC EQU  $24
; GFA_WS_MOUSE_X      EQU  $50
; GFA_SCORE           EQU  -$7E1C

    MOVE.L    GFA_WS_SCREEN_LOGIC(A4),D0  ; logical screen base
    MOVE.W    GFA_WS_MOUSE_X(A4),D1       ; current mouse X coordinate
    MOVE.L    GFA_SCORE(A5),D0            ; GFA global variable (int32)

Function Names

At the top of the disassembly, rg-dis reports the detected GFA-BASIC ABI and library version along with symbolic EQU definitions for the runtime routines called by the program:

Before

    JSR       -$0160(A6)
    JSR       -$4F04(A4)
    JSR       -$4BF6(A4)

After

; gfa: GFA-BASIC runtime, v3 frame ABI, library 3.50 (244 signature matches)
; Equates emitted in preamble:
; GFA_CALL_DFREE     EQU  -$0160
; GFA_CALL_RANDOMIZE EQU  -$4F04
; GFA_CALL_CLS       EQU  -$4BF6

    JSR       GFA_CALL_DFREE(A6)          ; DFREE: query free disk space
    JSR       GFA_CALL_RANDOMIZE(A4)      ; RANDOMIZE: seed random number generator
    JSR       GFA_CALL_CLS(A4)            ; CLS: clear screen

Function Arguments

GFA-BASIC v3 dispatches graphics, text, GUI, and system commands via negative A4 offsets. rg-dis replaces those offsets with symbolic GFA_CALL_* equates and traces the preceding register loads backwards to annotate command parameters right at the call site:

Before

    LEA       _L008410(PC),A2
    MOVEQ     #14,D0
    MOVE.W    #166,D2
    MOVE.W    #288,D1
    JSR       -$5E7A(A4)

    MOVEQ     #50,D0
    JSR       -$5018(A4)

    MOVEQ     #3,D0
    JSR       -$6460(A4)

After

    LEA       STR_TITLE(PC),A2            ; TEXT string pointer: "RESERVOIR GODS"
    MOVEQ     #14,D0                      ; string length: 14
    MOVE.W    #166,D2                     ; Y coordinate: 166
    MOVE.W    #288,D1                     ; X coordinate: 288
    JSR       GFA_CALL_TEXT_XY(A4)        ; GFA call: TEXT_XY(x=288, y=166, len=14, s="RESERVOIR GODS")

    MOVEQ     #50,D0                      ; delay: 50 frames (1.00s)
    JSR       GFA_CALL_PAUSE(A4)          ; GFA call: PAUSE (1.00s)

    MOVEQ     #3,D0                       ; color index: 3
    JSR       GFA_CALL_COLOR(A4)          ; COLOR C

Numeric Format

In GFA-BASIC, untyped numeric variables (x, i) and standard FOR loops default to GFA's built-in software floating-point type rather than 16-bit or 32-bit integers. Because the Atari ST has no FPU as standard, GFA uses its own custom software float format instead of IEEE-754: an explicit normalised mantissa followed by a 16-bit biased exponent and sign word (for example, 1.0 has mantissa $80000000... and exponent $03FF, while 36.0 has $90000000... and $0404).

In memory, 8-byte float variables and FOR loop descriptors store the mantissa in the first 6 bytes and the sign/exponent word at +6; in registers, GFA passes the mantissa in D0:D1 and the exponent/sign in D2.W. Because the compiler builds these constants piecemeal across several MOVE and CLR instructions, a raw disassembly just looks like a string of unrelated hex immediates. rg-dis tracks those writes, reconstructs the real value, and annotates the decoded loop bounds and constants inline:

Before

    LEA       -$7FC0(A5),A0
    MOVE.W    #$8000,(A0)+
    CLR.L     (A0)+
    MOVE.W    #$3FF,(A0)+
    MOVE.L    #$90000000,D0
    MOVEQ     #0,D1
    MOVE.W    #$404,D2
    LEA       -$7FC0(A5),A0
    JSR       -$5EE2(A4)

After

    LEA       -$7FC0(A5),A0               ; loop descriptor (init)
    MOVE.W    #$8000,(A0)+                ; loop start: 1.0
    CLR.L     (A0)+                       ; loop start: 1.0
    MOVE.W    #$3FF,(A0)+                 ; loop start: 1.0
    MOVE.L    #$90000000,D0               ; loop limit: 36.0
    MOVEQ     #0,D1                       ; loop limit: 36.0
    MOVE.W    #$404,D2                    ; loop limit: 36.0
    LEA       -$7FC0(A5),A0               ; loop descriptor
    JSR       -$5EE2(A4)                  ; FOR float loop init (start=1.0, limit=36.0)

Summary

Instead of staring at a wall of negative offsets off A4, A5, and A6 and trying to guess which GFA command or variable each number refers to, rg-dis does the detective work for you. It spots which GFA-BASIC runtime the program was compiled with, swaps raw offsets for readable command and variable names, fills in the arguments passed to each call, and turns GFA's split-up hex float constants back into normal numbers. You end up with a listing you can actually read and follow.