Fast Assembler (FA): Native Assembly Under SpartaDOS X and BW-DOS
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:
%101binary,$FFhex, 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
incis 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 numberon 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
$9Bline 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
iclneeds another open file. Raise the SPARTA driver's file count inCONFIG.SYSunder 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
- Picture: Fast Assembler's RAINBOW example: colours change on every scan line until START is pressed. — Program authors; screenshot by the site
- Fast Assembler 1.8 manual (Revision 17-09-2024), MMMG Soft 1995 / Holger Janz — GitHub project authors, 2024
- Fast Assembler README (versions 1.7 and 1.8, change list) — GitHub project authors
- FA.MAN manual page and README.DOC (1.8 package) — GitHub project authors
- Fast Assembler 1.8 examples (RAINBOW.ASM / RAINBOW.COM) — GitHub project authors
- MADS documentation (MADS oriented toward QA, XASM and FA users) — JAC; mads.atari8.info
- Mapping the Atari — memory map — AtariArchives.org
