Fast Assembler (FA): Native Assembly Under SpartaDOS X and BW-DOS

Rainbow colour bands across the text area of a GRAPHICS 0 screen, from the RAINBOW.ASM example

Not every Atari programmer wants a PC in the loop. Fast Assembler (FA) is a 6502 assembler that runs on the Atari under SpartaDOS X or BW-DOS (version 1.4 or later). Marek Goderski of MMMG Soft wrote it. His version 1.7 (1995) shipped on the SpartaDOS X Toolkit disk, and he later released it into the public domain. Holger Janz then produced version 1.8 (August 2024), which fixes long-standing bugs and makes it a complete package together with the XEDIT editor by FJC. FA is a true file-to-file assembler: neither source nor object is held in memory, so the size of a program is limited only by the disk.

What you'll learn: installing FA, its command line, source syntax, the blk block system for Atari DOS and SpartaDOS X files, symbols and relocatable programs, and how FA relates to MADS.

What you need: an Atari (real or emulated) running SpartaDOS X (any version) or BW-DOS 1.4+. The FA 1.8 package (also part of the SpartaDOS X add-ons). An editor that saves ATASCII text; XEDIT is included.

1. The package

Path Contents
BIN>FA.COM FA as a SpartaDOS X executable. Copy it to a directory on your $PATH
DOS>FA.COM FA as an Atari DOS-format executable for BW-DOS
MAN>FA.MAN Manual page, for the MAN command of SDX and BW-DOS
EXAMPLES> Commented examples: Atari DOS and SDX programs, fine scrolling, DLIs/VBIs, GTIA, POKEY music, an 8K cartridge
SDXLIB> A library for writing one source that builds as both an SDX and a BW-DOS program
SOURCES> FA's own source. It assembles itself under SDX (FA_SDX.ASM) or BW-DOS (FA_BWD.ASM)
TESTS> Test batch files for both DOSes

A good first session:

CD EXAMPLES
XEDIT RAINBOW.ASM
FA RAINBOW.ASM RAINBOW.COM
RAINBOW

Version note: FA 1.7 relied on undocumented SDX command-line parsing that was removed in SpartaDOS X 4.47 and restored in 4.49e. That means 1.7 fails on SDX 4.47–4.49d. Version 1.8 works with every SDX version.

2. Command line

FA [/L|S|E|Y|Q] src[.ext] [dst[.ext]]

Default extensions are .ASM and .OBJ, and the drive and path come from where you started FA. So FA MYPROG assembles MYPROG.ASM into MYPROG.OBJ. Progress looks like this:

Pass 0 Lines 42 Pending 1
Pass 1 Lines 42
Completed

On an error you get the file, line and program counter, then the message:

Error at D1:MY_SOURCE.ASM:13:3E40
  Undeclared label
Failed
Option Effect
/L List every line as read (includes expanded), with overall line number and PC
/S Summary: labels, blocks, memory use (useful to see how close you are to MEMTOP)
/E Turn assembly failure into a DOS error (224/$E0 and up), so batch files can test it with IF ERROR under SDX
/Y Write the symbol table to dst.SYM
/Q Quiet: one line per pass, for redirected output

3. Source syntax

FA is fully compatible with Quick Assembler syntax but not with MAC/65 or the Atari Assembler Editor. There are no line numbers. A label starts in column 1, and an instruction line starts with a space. Comment lines begin with * or (from 1.8) ;, and text after the operand is also a comment.

start   ldx #$08 set X register     ; label, instruction, comment
        asl @                       ; accumulator mode is written '@'
        lda <my_address             ; low byte
        ldy >my_address             ; high byte
  • Numbers: %101 binary, $FF hex, plain decimal. Values are calculated with 4 bytes.
  • Characters: 'A' is ATASCII, "A" is the internal screen code. A doubled quote inside means a literal quote: 'Windows ''95'.
  • Operators, highest priority first: & (AND), | (OR), ^ (EOR), *, /, +, -. Use [ ] to change the order. Up to 32 operators are allowed per expression.
  • * (only at the start of an expression) and ! (anywhere) mean the current program counter: *+4, $2300+!.
  • A label must not have the name of an instruction. A line starting with inc is read as the INC instruction.

Pseudo-instructions

Pseudo-op Meaning
label equ expr Define a value (names up to 240 characters)
dta b(…) a(…) v(…) e(…) f(…) g(…) l(…) h(…) Byte, address, relocatable address, 3-byte, 4-byte, 4-byte reversed, low byte, high byte
dta c'text' / dta d'text' ATASCII text / internal-code text
icl 'FILE.ASM' Include source (nesting depth limited by open files: about three levels with SDX's default of five)
ins 'PIC.DAT' Include binary data (new in 1.8)
label smb 'NAME' Use a SpartaDOS X symbol (must come before other declarations)
blk … Start a new block (below)
end End of source or include file
opt, org, lst Kept only for Quick Assembler compatibility

FA runs at least two passes, and up to eight in 1.8. Define equates in dependency order (c equ 100 before b equ c) so it doesn't need extra passes.

4. Blocks: Atari DOS and SpartaDOS X output

Every program is built from blocks (up to 256), and the block type decides the file header:

Statement Header / meaning
blk dos a Atari DOS segment ($FFFF) at address a. This is the equivalent of org/*=
blk sparta a SDX fixed-address block ($FFFA)
blk reloc main / extended Relocatable SDX block ($FFFE), loaded at MEMLO in main or extended memory
blk empty n main Reserves n bytes after relocatable code (no data stored)
blk update addresses $FFFD block that fixes up addresses in relocatable code
blk update symbols $FFFB block that resolves smb symbols
blk update new a 'NAME' $FFFC: export a new symbol (a leading @ makes it a command)
blk none a No header (ROM images)
blk padding a v No header. Pad with value v up to address a (new in 1.8; $FF is usual for ROMs)

An Atari DOS program: RAINBOW.ASM

This is the package's first example, unchanged:

* Example for FA
* Demo Atari Rainbow Color
* Atari DOS executable
* press START to end

RTCLK   equ $14
RUNAD   equ $02e0
COLPF2  equ $d018
CONSOL  equ $d01f
WSYNC   equ $d40a
VCOUNT  equ $d40b

* main program Atari DOS block
        blk DOS $3000
* reset console keys
start   lda #$08
        sta CONSOL
loop    clc
* calc next color
        lda VCOUNT
        adc RTCLK
* wait for sync
        sta WSYNC
* set color
        sta COLPF2
* check START
        lda CONSOL
        and #$01
        bne loop
        rts

* run address Atari DOS block
        blk DOS RUNAD
        dta a(start)

        end

Each scan line it adds the frame counter (RTCLOK's fast byte at $14) to VCOUNT, waits for horizontal sync, and stores the result in the GR.0 background colour, until bit 0 of CONSOL shows START pressed. The second block simply loads the start address into RUNAD. Build it with FA RAINBOW.ASM RAINBOW.COM and run it by typing RAINBOW.

A relocatable SpartaDOS X program

SDX programs don't need a fixed address. A reloc block is loaded at MEMLO, and the system symbols are linked by name when the program loads. The package's HELLO.ASM, unchanged:

* Example for FA
* Hello from Atari
* SpartaDOS X executable with
* relocatable code 

* used SpartaDOS X symbols
* see SDX programming guide
PRINTF  smb 'PRINTF'
GETS    smb 'GETS'

* name buffer size
nam_siz equ $40

* relocatable code block
        blk reloc main
* print question
        jsr PRINTF
        dta c'What''s your name?'
        dta b($9B,$00)
* get name, due to code
* relocatability you cannot use
* lda <name and ldx >name because at
* compile time we do not know where
* the program will be located!
        lda namev
        ldx namev+1
        ldy #nam_siz
        jsr GETS
* print greetings
        jsr PRINTF
        dta c'Hello %s !'
        dta b($9b,$00)
        dta v(name)
        rts
* vector is needed for get name
namev   dta v(name)

* relocatable data block
* program counter is incremented!
* by BLK EMPTY, symbols must be
* definded beforehand
name    equ *
        blk empty nam_siz main

* blocks for address and symbol update
        blk update addresses
        blk update symbols

        end

If you misspell a symbol (PRINTFX), it still assembles, but SDX stops at load time with 154 Symbol not defined. Other examples show memory-resident programs (set the INSTALL symbol to $FF before exiting, and export commands with blk update new), calling one program from another with U_LOAD, and new external commands that report errors through STATUS. SDX allows at most seven relocatable blocks. Keep fixed sparta blocks below $1000 or well above your relocatable code, because FA assumes addresses from $1000 up belong to reloc and empty blocks and won't catch a collision.

5. FA and MADS

MADS was designed with users of Quick Assembler, XASM and FA in mind, and it accepts FA syntax. In practice that means you can edit and build FA sources on a PC and move them back and forth. For example, the package's RAINBOW.ASM, once its ATASCII line ends are converted, assembles under MADS 2.1.7 to a file byte-for-byte identical to the RAINBOW.COM that FA produced.

Troubleshooting

  • FA does nothing or misreads its parameters under SDX 4.47–4.49d. You're running 1.7. Use 1.8.
  • Too big number on every multiply or divide. This was a 1.7 overflow bug, fixed in 1.8.
  • "Unexpected end of line" on blank lines. 1.7 rejected blank lines containing spaces. 1.8 accepts them.
  • Garbage or one giant line when assembling a file edited on a PC. The source must be ATASCII with $9B line ends. Convert it (Altirra's H6:–H9: host devices translate line endings when files pass through them).
  • Out of Memory. The symbol table reached MEMTOP. Check with /S, free memory (unload drivers, use a DOS with lower MEMLO), or split the program into fewer labels.
  • Include nesting fails. Every nested icl needs another open file. Raise the SPARTA driver's file count in CONFIG.SYS under SDX (BW-DOS is fixed at five).

Further reading

  • The full FA 1.8 manual (FastAssembler.pdf), including the SDX Lib chapter and the list of error messages.
  • The SpartaDOS X Programming Guide for the symbols (PRINTF, GETS, U_LOAD, COMTAB…) that FA programs call.
  • FA has been used for BW-DOS itself, FujiNet command-line tools for SpartaDOS, and sources for the XL operating system .

Credits