Reference

Output formats

The dialect tour covers every assembler syntax rg-asm can read. This page covers what it can write: GEMDOS executables, linkable objects for classic and modern toolchains, Motorola DSP56001 binaries and loaders, raw flat images, and the symbol tables embedded in a .PRG.

Output Kinds

Everything rg-asm emits is one of four kinds, selected by CLI flags. The difference is who resolves addresses:

Kind	Flag	Default name	Relocations resolved by
Executable	--prg (default)	<input>.PRG	GEMDOS loader (PEXEC relocation table)
Object	--obj[=KIND]	<input>.o	The linker (rg-asm built-in or rg-link / vlink)
Raw	--raw	<input>.BIN	None (bytes must already be final)
DSP Co-processor	--format=FMT	<input>.lod / .p56 / .dsp	Falcon XBIOS, DSP memory loader, or host 68030 feeder

Atari-bound artifacts use UPPERCASE extensions (.PRG, .BIN); objects stay lowercase .o because they are host toolchain intermediates. An explicit -o path is honoured verbatim: GAME.TOS, DESK.ACC, and TOOL.TTP are the same GEMDOS container; only the desktop launch hint differs.

GEMDOS Executables

The Atari ST executable format, also used for .APP, .GTP, .ACC, and .TTP. All multi-byte fields are big-endian. The file begins with magic $601A, literally a bra.s over the header, which a debugger can step over.

28-byte header

Offset	Size	Field	Notes
0x00	word	magic	$601A
0x02	long	text size	bytes of code segment in file
0x06	long	data size	bytes of initialised data in file
0x0A	long	BSS size	uninitialised RAM (not stored in file)
0x0E	long	symbol table size	0 when stripped (--strip)
0x12	long	reserved	0 (Pure C expects this)
0x16	long	flags	GEMDOS PRGFLAGS (see below)
0x1A	word	absflag	0 = relocation table follows; non-zero = no relocs

Header flags (--prg-flags)

The flags longword at offset 0x16 controls load behaviour. Memory protection tokens share bits 4-7; pick one mode for --prg-flags.

CLI token	Bit	Effect
fastload	0	Clear BSS only on load, not the whole heap
fastram	1	May load into TT-RAM
fastalloc	2	Malloc may use TT-RAM
private global super readable	4-7	Private memory protection (mode 0) Global memory protection (mode 1) Supervisor memory protection (mode 2) Readable memory protection (mode 3)

File layout

Relocation table

When absflag is 0, GEMDOS loads the program at an arbitrary base and patches absolute longwords in the combined text+data image using a compact byte stream appended after the optional symbol table. The table starts with a longword offset to the first fixup site; 0 means no relocations. Fixup offsets must be even (68000 alignment).

Table byte	Action
$00	End of relocation table.
$01	Advance the fixup offset by 254 bytes without patching (long gap).
$02…$FE (even)	Advance the fixup offset by this many bytes, then add the load base to the longword at that offset in the image.

Loader pseudocode

// image: text || data loaded at `base`; rt points at the relocation table in the file
offset = be32_read(rt)
if offset == 0: return

p = rt + 4
loop:
    b = u8_read(p++)
    if b == 0: break
    if b == 1:
        offset += 254
        continue
    offset += b
    u32_at(base + offset) += base

The long-gap byte is $01, not $FE; $FE (254) is a valid even step that also performs a patch. rg-link and rg-asm emit absflag 0 with a full table (TurboAss / GEMDOS style). GenST 1.01 uses absflag $FFFF and a single trailer $00 instead.

Symbol tables (DRI, GST, extern)

Executables can carry an embedded symbol table for debuggers and profilers, controlled by --sym=KIND (default gst). Use --strip to omit it entirely.

--sym	Format	Where it lives	Typical consumer
dri	DRI (8-char names)	Embedded in .PRG	Classic Atari debuggers, Hatari (limited)
gst	GST (DRI + long-name continuations)	Embedded in .PRG	Devpac/HiSoft profilers, extended debuggers
extern	Plain text (ADDR t name, nm-style)	Sidecar .sym file	Hatari, godbox source-level debug

Provenance: DRI and GST symbol tables come from the Digital Research GEMDOS / CP/M-68K toolchain; GST extended them for names longer than 8 characters (Devpac/HiSoft). Hatari and godbox are consumers, not authors, of these formats.

DRI symbols use 14-byte records (8-char name + type word + value). GST adds continuation records for long names. The embedded table is separate from linkable object formats: it lives inside the finished executable, not in a .o file.

Linkable objects (--obj=KIND)

--obj emits one relocatable object per source file. The KIND selects which linker ecosystem the object targets. rg-asm's built-in linker and rg-link ingest ELF natively and transcode GST, a.out, Pure C, and DRI objects to ELF at read time, so mixed links work through one pipeline.

KIND	Magic / marker	Typical consumer	Notes
elf (default)	ELF	vlink, vbcc, gcc-binutils	ELF32 big-endian m68k; modern toolchain path
gst	$FB directive stream	Devpac, HiSoft, GenST linkers	Classic Atari .O; vasm -Fgst oracle
dri	$601A + 28-byte header	Alcyon / DR AS68, RMAC family	Word-parallel reloc bitmap; 8-char DRI symbols
purec (pc)	$4EFA	Pure C, Lattice C, AHCC (PLINK / AHCL)	Atari "group 1" object; AHCL-validated emit
aout	$0107 (OMAGIC)	MiNT, BSD a.out toolchains	Round-trip oracle via vlink -baoutmint
lout (mwc)	$0107 LE	Mark Williams C as	Coherent-family l.out; minimal emit
seka	$A001 framing	Andelos / K-Seka	Framed linkable (A0 01 …)
hunk (amiga)	HUNK_*	Lattice Amiga	Amiga hunk format, not GST

ELF32 m68k

Default object format. Sections (.text, .data, .bss) carry standard ELF relocations (R_68K_32, PC-relative variants, etc.). This is the format vbcc and gcc emit when targeting vlink, and what rg-asm's linker consumes directly.

GST object

A flat byte stream of directives. Any byte that is not part of a directive is literal section data. Directives begin with escape byte $FB; a literal $FB in data is written as $FB $FB.

Directive	Layout	Meaning
FB 01	len.b name[len]	Source file name (debug)
FB 04	id.w	Select current section
FB 06	len.b name[len] value.l secid.w	Defined symbol (export)
FB 07	addend.l size.b flag.b target.w	Relocated field
FB 10	id.w len.b name[len]	Section (negative id) or external xref (positive id)
FB 13	(none)	End of object

Library archives use magic $FB01 (GMAGIC) with GST members inside. vlink does not read GST objects. Correctness is verified by byte-matching vasm -Fgst output.

DRI / Alcyon object

Shares the executable magic $601A but is disambiguated by layout: a 28-byte header (same field order as PRG) followed by text, data, a symbol table, and a word-parallel relocation bitmap with one 16-bit slot per image word.

Reloc slot	Meaning
$0000	No relocation at this word
$0001 / $0002	Low word, internal reference (GenST vs vasm differ)
$0005	High word of a 32-bit absolute relocation
n×8+4	Low word, external reference to symbol n

DRI library archives use magic $FF65 (DLMAGIC). Emitted with --obj=dri; pair with --dialect=alcyon or RMAC-family dialects.

Pure C object (group 1)

The object format shared by Pure C, Lattice C, and AHCC. It is mutually incompatible with gcc/vbcc ELF at the object level, but interoperable among group-1 tools. Magic $4EFA (PMAGIC); the second word is fixed at $001C (PPMAGIC). All fields are big-endian.

32-byte header

Offset	Size	Field	Notes
0x00	word	magic	$4EFA (PMAGIC)
0x02	word	he	$001C (PPMAGIC), always this value
0x04	long	limage	Image length (text + data concatenated)
0x08	long	lfixup	Fixup stream length in bytes
0x0C	long	lnames	Names section length
0x10	long	lsym	Symbol section length (0 in plain objects)
0x14	long	res1	Reserved (0)
0x18	long	res2	Reserved (0)
0x1C	long	hekp	Reserved (0)

File layout

Fixup record (FIX, 4 bytes)

Offset	Size	Field	Notes
+0	byte	ty	Fixup type (FIX_text, FIX_labs, …)
+1	byte	sk	Skip: byte delta from previous record's position to this one
+2	word	nnr	Name index into the names section, or -1 if none

ty	Name	Meaning
1	FIX_end	End of fixup stream
2	FIX_step	Large position advance (24-bit × 256)
3	FIX_text	Start of TEXT segment
4	FIX_data	Start of DATA segment
5	FIX_bss	Start of BSS segment
7	FIX_glmod	Global module (exported) start
9	FIX_lcmod	Local module start
11	FIX_labs	32-bit absolute relocation at current position
12	FIX_wabs	16-bit absolute relocation
13	FIX_lpcrel	32-bit PC-relative relocation
14	FIX_wpcrel	16-bit PC-relative relocation
17	FIX_wbra	Word branch (PC-relative)
18	FIX_sbra	Short branch (PC-relative)

rg-asm emits Pure C objects (--obj=purec) validated by AHCC's real AHCL.TTP linker under emulation. It reads both Pure C ($4EFA) and DRI ($601A) inputs when linking.

BSD / MiNT a.out

Classic Unix a.out relocatable (OMAGIC $0107, big-endian on Atari). Same broad shape as many host toolchains: fixed exec header, segment blobs, relocation records, then symbol and string tables. Oracle-validated through vlink -baoutmint round-trips with vasm -Faout.

Exec header (32 bytes)

Offset	Size	Field	Notes
0x00	long	a_info	$00010107 (OMAGIC in low word)
0x04	long	a_text	Text segment size
0x08	long	a_data	Data segment size
0x0C	long	a_bss	BSS size (not stored in file)
0x10	long	a_syms	Symbol table size (12 × n symbols)
0x14	long	a_entry	Entry point (0 for objects)
0x18	long	a_trsize	Text relocation size (8 × n)
0x1C	long	a_drsize	Data relocation size (8 × n)

File layout

Relocation record (8 bytes)

Offset	Field	Notes
+0	r_address	Offset of the field within its segment
+4	r_info	Symbol/segment index in bits 31-8; flags in low byte (pcrel, length, extern)

Section-relative fields hold seg_base + addend; external fields hold the addend alone.

MiNT a.out executables (GEMDOS-wrapped) are a separate follow-up; the modern MiNT/GNU path already consumes ELF from rg-asm.

Heritage and niche objects

l.out, Seka, and Amiga hunk sit outside the main GST / DRI / Pure C / a.out line. They do not share one on-disk layout: a.out and l.out are header+segment cousins; Seka is a framed byte stream; hunk is a tagged longword sequence. The matrix below is an at-a-glance map; each format has its own detail section.

Aspect	a.out	l.out	Seka	hunk
Magic / marker	$0107 OMAGIC (BE)	$0107 (LE)	$A001 frame words	HUNK_* tags
Header	32-byte exec header	48-byte Coherent header	None (inline framing)	HUNK_UNIT … HUNK_END
Segments	text, data, bss (implied)	text, data (minimal emit)	TEXT frame, optional DATA frame	CODE / DATA / BSS hunks
Relocations	8-byte records per segment	Not emitted yet	A1 02 inline tags	Not emitted yet
Symbols	nlist + string table	Not emitted yet	A3 GLOBL records	In hunk stream (Lattice)
rg-asm emit	Full	Text/data only	TEXT/DATA + relocs	TEXT (+DATA/BSS basic)

l.out (Mark Williams C)

Coherent-family relocatable used by MWC as (--obj=lout). Shares the $0107 magic with a.out but is little-endian and uses a 48-byte header. rg-asm currently emits text (+ optional data) only; symbol and relocation tables are still growing.

Seka (Andelos / K-Seka)

Framed linkable for K-Seka (--obj=seka). No fixed header: the file is a byte stream of 16-bit frame words and payload. Words in the $A000…$AFFF range are escaped so they cannot be mistaken for control tags.

Tag	Layout	Meaning
A0 00	word	Escape: literal payload word in $A000…$AFFF
A0 01	(none)	TEXT section open / close frame
A0 02	(none)	DATA section open / close frame
A1 02	zero.l	Absolute relocation site (placeholder patched at link time)
A3	name…	Exported GLOBL symbol

Amiga hunk (Lattice)

Lattice Amiga object format (--obj=hunk), not GST despite the shared vendor. A sequence of big-endian longword tags and payloads; minimal emit is HUNK_UNIT → named CODE (or DATA/BSS) → HUNK_END.

Tag	Name	Meaning
$03E7	HUNK_UNIT	Start translation unit (+ name)
$03E8	HUNK_NAME	Name the following hunk
$03E9	HUNK_CODE	Initialised executable bytes (longword-padded)
$03EA	HUNK_DATA	Initialised data
$03EB	HUNK_BSS	BSS size (longwords, no bytes)
$03F2	HUNK_END	End of hunk block

Raw .BIN

--raw writes a flat memory image: no header, no symbol table, no relocation records. Addresses must be final at assembly time. Use PC-relative code or ORG for absolute placement. ORG is honoured for raw output and ignored for --prg and --obj.

Raw output enforces two constraints: one effective section (sections are concatenated into a single buffer) and no undefined symbols (nothing left for a linker to resolve). The boot-sector idiom text / org $600 / … is the classic use case.

Motorola DSP56001 Formats (--format=FMT)

When assembling Motorola DSP56001 code (invoked via --cpu=56001, DSP source extensions like .s56 or .asm56, or in-file .56001 blocks), rg-asm can target seven distinct output representations. These range from classic text loaders for Atari Falcon XBIOS to high-speed binary containers, industry-standard Motorola COFF, and embeddable host C/ASM tables.

Format	CLI Flag	Default Ext	Word Layout	Primary Consumer & Use Case
Motorola .LOD	--format=lod	.lod	ASCII hex (24-bit)	Atari Falcon XBIOS Dsp_ExecProg, Hatari, Motorola debuggers (default).
Brainstorm .P56	--format=p56	.p56	Packed binary (3 bytes/word)	Atari demoscene multi-segment loader; zero gap overhead between P/X/Y runs.
GODLIB .DSP	--format=dsp	.dsp	Unpacked binary (4 bytes/word)	sDspBinary container; 32-bit longwords for unrolled 68030 host port blasting.
Raw Flat .BIN	--format=bin / --raw	.bin	Packed (3B) or unpacked (4B)	Direct memory images, EEPROMs, or custom Falcon DMA buffers.
a56 .OUT	--format=out	.out	ASCII per-word + symbols	Quinn Jensen a56 compatibility and legacy DSPMAKE pipelines.
Motorola COFF	--format=cld / --format=cln	.cld / .cln	COFF binary (3 bytes/word)	Motorola DSP suite (dsplnk, sim56, cldlod); absolute or relocatable.
Embeddable C	--format=c / --format=c.3	.c	C source arrays	Static arrays (uint32_t or uint8_t) compiled directly into host programs.
Embeddable ASM	--format=inc / --format=asm.3	.inc	680x0 dc.l / dc.b	Host 68k assembly tables ready for direct include.

Motorola .LOD (--format=lod)

The canonical ASCII format developed by Motorola and the default output for standalone DSP assembly. .LOD files are human-readable, streamable text files directly accepted by the Atari Falcon operating system through the XBIOS call Dsp_ExecProg (Opcode 96) as well as emulators and system monitors.

An rg-asm .LOD file consists of four record varieties:

Record	Syntax	Description
_START	_START <symbol> <hex_addr>	Defines the entry point address in P-memory (e.g. _START Start 0040). If no entry symbol is found, defaults to _START MAIN.
_DATA	_DATA <space> <start_addr>	Declares the start of a contiguous run in space P, X, or Y at a 4-hex-digit word address, followed by lines of up to 8 space-separated 6-hex-digit (24-bit) words.
_BLOCKDATA	_BLOCKDATA <space> <addr> <count>	Emitted for block-fill directives (e.g. bsc). Specifies target space, start address, repetition count, followed by the single 6-digit hex fill word on the next line.
_END	_END	Marks the end of the loader stream.

Entry points can be set explicitly via --entry-symbol=<NAME>, or inferred automatically from standard symbols (Start, Entry, or Init). Starting addresses can be overridden from the command line using --org-p=<HEX>, --org-x=<HEX>, and --org-y=<HEX>.

Brainstorm .P56 (--format=p56)

Pioneered by the Brainstorm demogroup, .P56 is a compact multi-segment binary format widely used across the Atari Falcon 030 demoscene. Unlike flat binaries, .P56 can represent disjoint allocations in program memory and X/Y data memory without filling the intervening address gaps with zeros.

A .P56 file has no monolithic file header. Instead, it is a sequential stream of binary segments:

Host upload routines can parse each 9-byte header, configure the DSP base address register, and stream the $N$ words into the DSP host interface register.

GODLIB .DSP (sDspBinary)

The structured binary format used by the Reservoir Gods GODLIB library runtime. While .P56 prioritises minimum disk size, .DSP is architected around host transfer throughput on the 16 MHz MC68030 bus.

Each 24-bit DSP word is stored in a 4-byte big-endian slot: 0x00, High, Mid, Low. Because the most significant byte is zero, the Falcon 68030 host CPU can blast longwords directly from ST-RAM into the DSP Host Interface data register ($FFFFA204) using an unrolled move.l (a0)+,(a1) loop with zero shifting, masking, or byte-packing overhead.

sDspBinary 28-byte Header

Flat .BIN & a56 .OUT

Raw Flat Binary (--format=bin)

--format=bin (or --raw with a DSP target) produces a pure memory dump containing only instruction words with no headers, metadata, or segment framing. Contiguous runs are output in ascending address order. By default, words are written in packed 24-bit big-endian format (3 bytes per word). When combined with --unpacked, each word is padded to 4 bytes with a leading zero byte.

Quinn Jensen a56 (--format=out)

Emits the ASCII word-by-word representation produced by Quinn Jensen's legacy a56 assembler. Each word is printed on its own line as <space> <addr:04X> <word:06X>. The file concludes with a deterministic symbol trailer sorted alphabetically by symbol name:

P 0040 0A7004
P 0041 00FFE8
I 000040 Start
F 400000 VolumeHalf

Integer equates and labels are prefixed with I, while fractional constants are marked with F.

Motorola DSP COFF (.CLD & .CLN)

rg-asm implements full emit support for the Motorola Common Object File Format (COFF) standard (magic 0x01E0) used by Motorola's official DSP56000 toolsuite (including dsplnk, the sim56 simulator, and cldlod).

• Absolute Load Executable (--format=cld): Contains a 20-byte file header, a 28-byte optional a.out header specifying execution entry addresses, section headers for .text (P-space), X_DATA (X-space), and Y_DATA (Y-space), raw section data (3 bytes per word), an 18-byte per-entry symbol table, and a string table for symbols longer than 8 characters.
• Relocatable Object (--format=cln): Emits relocatable section definitions and symbol records without the optional execution header (opthdr_size = 0), ready for linking with Motorola dsplnk.

Embeddable C & ASM Tables

For projects where DSP kernels are linked directly into the host executable rather than loaded from disk as external files, rg-asm can transpile assembled DSP code into embeddable C headers and 680x0 assembly tables.

C Header Arrays

Selected via --format=c (or --format=c.4 for 32-bit unpacked, --format=c.3 for 24-bit packed bytes). Generates a complete C compilation unit with size constants:

/* Generated by rg-asm */
#include <stdint.h>
#include <stddef.h>

const uint32_t dsp_code[] = {
    0x000A7004, 0x0000FFE8, 0x00200000
};

const size_t dsp_code_len = sizeof(dsp_code) / sizeof(dsp_code[0]);

680x0 Assembly Include Tables

Selected via --format=inc (or --format=asm.4 for 32-bit dc.l, --format=asm.3 for 24-bit dc.b). Outputs structured assembly data with alignment and extent markers:

; Generated by rg-asm
    even
dsp_code:
    dc.l    $000A7004,$0000FFE8,$00200000
dsp_code_End:
    even

The symbol name (default dsp_code) is customized with --entry-symbol=<NAME>.

In-File Mixed-Mode Wire Formats

Instead of maintaining separate .s and .s56 source files, rg-asm allows writing 680x0 host routines and DSP56001 microkernels within the same source file. Target switching is achieved via RMAC-style directives:

; --- 68030 host code ---
    move.w  #$2700,sr
    bsr     UploadDspKernel

; --- Inline DSP56001 kernel ---
    .56001  unpacked
    org     p:$40
Start:
    movep   #0,x:<<$FFFE    ; disable BCR bus wait states
    rts
    .68030

; --- 68030 resumes ---
UploadDspKernel:
    lea     Start,a0
    ; ... upload loop ...

Wire Modifiers

The opening directive (.56001, pushcpu 56001, or cpu 56001) accepts modifiers controlling how the sub-assembled DSP binary is placed into the host 68k section:

Modifier	Layout	Description
unpacked	4 bytes / word (dc.l)	Default. Words are emitted as $00xxxxxx longwords for fast 32-bit host-port transfer.
packed	3 bytes / word (dc.b)	Words are packed tightly as 3 raw bytes ($xx,$xx,$xx) to minimize host binary footprint.
bootstrap	Header + 4B words	Automatically prepends Falcon host bootstrap preamble (word count + P-memory load address) before the unpacked words.
noeven	(none)	Suppresses the trailing even alignment directive that is otherwise automatically emitted after the DSP payload.
org=p:$addr	Address	Explicitly sets the DSP memory origin if not defined by an internal org directive.

To return to host code, use .68000, .68030, popcpu, or cpu 68000. Host 68k equates are seamlessly available inside the DSP block, and DSP labels and equates are automatically exported back to the host 68k symbol table.

---

For every CLI flag, worked examples, and JSON machine output, see the full documentation. For input syntax history, see the dialect tour.