ATasm: Cross-Assembling MAC/65-Style Source on a Modern PC
ATasm is a 6502 cross-assembler by Mark Schmelzenbach. He wrote it because he missed OSS's MAC/65 cartridge and wanted a fast, Atari-aware assembler on a PC. It reached its first public release (0.90) on 1 January 1999, and the bundled manual describes version 1.08 from 2014. ATasm stays close enough to MAC/65 that the MAC/65 manual still works as a reference. That makes it a natural choice if you are reviving 1980s source code or learning from magazine listings written for MAC/65 or the Assembler Editor.
What you'll learn: ATasm's command line, its MAC/65-flavoured syntax and directives, macros and repeat blocks, .BANK for cartridges and INIT segments, assembling directly into disk images or emulator snapshots, and where it differs from MAC/65.
What you need: an ATasm binary, or its C source, which builds with make on UNIX-like systems (zlib is needed for snapshot support). You'll also need an emulator.
1. Command line
The options (each is joined directly to its argument, with no space):
atasm [options] <fname.m65>
-v print assembly trace
-s print symbol table
-u enable undocumented opcodes
-r save object code as a raw binary image (.bin)
-f[value] fill byte for raw images (default $FF)
-o[fname] object file name
-d[sym=val] pre-define a symbol
-Idirectory search directory for .INCLUDE (and, from 1.08, .INCBIN)
-l[fname] dump labels to a file
-g[fname] write a debug list file
-x[fname] write the object file into an .XFD/.ATR disk image
-m[fname] overlay the object onto an emulator state file
-mae treat local labels like the MAE assembler
By default atasm sample.m65 produces sample.65o, a standard Atari binary-load file that DOS 2.5's L command can load. Some typical uses:
atasm -ogame.xex -lgame.lab game.m65 # executable plus label file
atasm -DDEBUG -DLEVEL=3 game.m65 # command-line defines
atasm -xwork.atr game.m65 # also copy GAME.65O into work.atr
atasm -r -f0 cart.m65 # raw image, gaps filled with $00
Notes:
-Dvalues must be numbers.-DBASICdefines BASIC as 1, and-DOSB=defines OSB as 0. For hex, write$xxxx, and escape the$in shells that need it.-xneeds a single- or enhanced-density image formatted with DOS 2.0S/2.5 or a compatible DOS. An existing file of the same name is overwritten.-mreads a saved atari800 (or Atari800Win) state file, lays your code over it, and writes a new snapshot you can load straight away. Atari++ snapshots have been supported since 1.05.
2. Source format
[line number] [label] [opcode operand] [;comment]
Line numbers are optional and ignored, so old MAC/65 listings typed with numbers assemble as they are. Input is case-insensitive. Labels may start with a letter, @ or ? (or a leading underscore, from 1.07). Comments must start with ;. MAC/65's * comment lines are not accepted.
Constants follow MAC/65 rules:
| Form | Meaning |
|---|---|
$1A |
hex |
~1010 |
binary (note: tilde, not %) |
'A |
a single character (one quote) |
"TEXT" |
a string |
>expr / <expr |
high / low byte |
[ ] |
grouping (square brackets, so they aren't confused with indirect addressing) |
Operators include * / + -, & (AND), ! or | (OR), ^ (EOR), comparisons, and .AND, .OR, .NOT, .DEF, .REF, .BANKNUM. Unlike MAC/65, ATasm gives unary < and > their proper precedence: #>1000+2000 means (>1000)+2000, whereas MAC/65 treated it as >(1000+2000). Watch for that when you port old code.
3. A small program
; border.m65 -- cycle the border colour until a key is pressed
; atasm -oborder.xex -lborder.lab border.m65
COLOR4 = $02C8 ; border colour shadow (712)
RTCLOK = $12 ; frame clock; RTCLOK+2 ticks every 1/60 s (NTSC)
CH = $02FC ; last key, $FF = none
*= $2000
START LDA #$FF
STA CH
LOOP LDA RTCLOK+2
STA COLOR4
LDA CH
CMP #$FF
BEQ LOOP
LDA #$FF
STA CH
RTS
*= $02E0 ; RUNAD
.WORD START
The last two lines are the classic way to make an auto-running binary in any MAC/65-family assembler. Setting the origin to $02E0 starts a new segment that loads RUNAD.
4. Directives worth knowing
*=addrsets the origin..DS n(or*=*+n) reserves space..DC n,bytefillsnbytes with a value.label = exprdefines a constant.label .= exprdefines a symbol you may redefine later (useful inside.REPT)..BYTE,.SBYTE(converted to screen codes),.CBYTE(last byte EOR$80, a common string terminator),.DBYTE(big-endian words),.WORD(little-endian) and.FLOAT(six-byte BCD as used by the OS math pack). A leading+valueadds a constant to every byte on the line:.BYTE +$80,"TEXT"gives inverse text..IF expr / .ELSE / .ENDIFfor conditional assembly..INCLUDE filecan be nested to any depth (MAC/65 allowed one level)..INCBIN filepulls in fonts, maps and other binary data..ERROR "msg"stops assembly..WARN "msg"counts a warning..OPT [NO] ERR|OBJ|LIST|ILL.NO OBJassembles without generating code.ILLenables undocumented opcodes in one region only..LOCALstarts a new local region. Labels beginning with?are private to it, and there can be up to 65,536 regions (MAC/65 allowed 62).
Macros and repeats
Macro parameters are %1, %2… as expressions, or %$1 as strings. %0 is the parameter count. Labels inside a macro are local to it. This example, from ATasm's documentation, installs a display-list interrupt:
.MACRO VDLI
.IF %0<>1
.ERROR "VDLI: Wrong number of parameters"
.ELSE
ldy # <%1
ldx # >%1
lda #$C0
sty $0200 ; VDSLST low
stx $0201 ; VDSLST high
sta $D40E ; NMIEN: enable DLI + VBI
.ENDIF
.ENDM
.REPT n … .ENDR repeats a block. This example builds a 192-entry row-address table for a 40-byte-wide bitmap:
table .rept 192
.word [*-table]/2*40
.endr
.BANK and .SET 6
.BANK starts a fresh assembly "bank" that is appended to the output file, while labels stay visible across banks. It has two uses. One is building cartridge images bigger than 64K. The other is writing multi-segment loaders with INIT segments:
.bank
*=$4000
init .include "initcode.asm"
.bank
*=$2E2 ; INITAD: DOS JSRs here as soon as it loads
.word init
.bank
*=$6000
.include "restofthecode.asm"
.SET 6,expr assembles code to run at a different address from where it is stored. Use it for routines that are copied out of a cartridge or banked memory into RAM.
5. Differences from MAC/65 to remember
ATasm reads plain ASCII text, not MAC/65's tokenized SAVE files. In MAC/65, LIST the source to disk first, then convert ATASCII to ASCII with a tool. Other differences: no * comment lines; macro names must be unique and can't match a label; macro parameters may be separated by spaces or commas; .END, .PAGE, .TAB and .TITLE are ignored; and opcodes are reserved words that can't be used as labels.
6. Debugging with Altirra
With ATasm's -l label output, Altirra offers label translation only. Its listings don't carry source-line information, so you get symbolic disassembly but no source stepping. Name the label file after the executable (-oborder.xex -lborder.lab) and Altirra loads it automatically when you boot the program. If you want source-level debugging, MADS supports it fully.
7. Editor integration
ATasm has long been supported by the WUDSN IDE for Eclipse. A simple VS Code tasks.json build task can run:
atasm ${relativeFile} -mae -Iincludes -IUtility -o${fileBasenameNoExtension}.com
along with a problem matcher keyed on ATasm's In file, line N-- error lines, so double-clicking an error takes you to the line. The "Atasm Altirra Bridge" extension wraps the same idea with one-click assemble-and-run.
Troubleshooting
PHASE ERROR. A forward-referenced symbol changed size between passes. ATasm tries extra passes, but declaring zero-page equates before you use them avoids the problem.- Strange values after porting from MAC/65. Check expressions that use
<and>against the precedence rule in section 2. - Undocumented opcodes are rejected. Use
-u, or wrap that code in.OPT ILL. .INCBINcan't find the file. Before 1.08, include paths applied only to.INCLUDE. Use a full path, or upgrade.- The disk image is rejected by
-x. The image must be single or enhanced density and formatted with DOS 2.0S, DOS 2.5 or a compatible DOS. A SpartaDOS-format image won't work.
Further reading
- The MAC/65 reference manual (OSS). ATasm's author recommends it as a companion, and its macro chapter (with
iomac.lib) shows more advanced techniques. The ATasm package'sexamples/sample.m65usesiomac.libI/O macros such asOPEN,BPUT,PRINTandCLOSE. - The manual's appendices list legal and undocumented 6502 opcodes and addressing modes.
- EnvisionPC, the same author's PC version of the APX Envision character and map editor, pairs naturally with ATasm for game graphics.
Credits
- ATasm v1.08 manual (atasm.txt), Mark Schmelzenbach — atari.miribilist.com
- ATasm version history (VERSION.TXT) and source (src/asm.c) — atari.miribilist.com
- ATasm examples (sample.m65, iomac.lib) — atari.miribilist.com
- Altirra help — symbol support for ATasm — Screenshot from Avery Lee's Altirra page, virtualdub.org
- AtariAge — Windows Tools for Atari Programming — AtariAge forum members
- AtariAge — Visual Studio Code (ATasm build task) — AtariAge forum members
- Mapping the Atari — memory map — AtariArchives.org
