Coding the Classic Way: Atari Assembler Editor and OSS MAC/65
Open almost any 1980s Atari assembly book or magazine tutorial and it assumes one of two tools. Mark Chasin's Assembly Language Programming for the Atari Computers used Atari's Assembler Editor cartridge, which he called the most widely owned (though "certainly not the most powerful") assembler. Hobbyists who got serious moved on to MAC/65 from Optimized Systems Software (OSS). If you want to type in those listings exactly as published, or just feel what 1982 was like, this guide shows you how to drive both.
What you'll learn: where the tools came from, line-entry rules, the editor commands, assembling to memory or disk, the debugger, and how MAC/65 differs.
What you need: an Atari or an emulator, the Assembler Editor or MAC/65 cartridge (or MAC/65 on disk with DOS XL), and a DOS disk. In Altirra, mount the cartridge image and a DOS 2.5 disk, then add the H: host device (System > Devices) so you can save files straight to your PC.
1. A little history
Atari shipped the Assembler Editor cartridge, written by Shepardson Microsystems, Inc. (SMI), in winter 1981. SMI's credits list Kathleen O'Brien, who also wrote Atari BASIC's floating-point routines. On 25 February 1981 the newly founded OSS bought the source code to Atari BASIC, DOS 2.0S's FMS and the Assembler Editor from SMI. In April 1981 it introduced EASMD, an enhanced disk-based Assembler Editor. MAC/65, conceived and written by Stephen D. Lawrow (manual copyright 1982–83 by OSS and Lawrow), grew out of EASMD. That's why both tools still look and feel so alike.
One compatibility warning: the original orange-label MAC/65 version 1.00 requires the 400/800 OS. Every later release works on XL/XE machines.
2. Line entry rules (both tools)
Every source line starts with a line number (0–65535) followed by exactly one space. After that:
- A label starts immediately in that next column.
- With no label, leave two spaces after the line number before the mnemonic. Leave only one and the assembler takes your mnemonic for a label.
- The operand follows the mnemonic after at least one space. Anything after the operand is a comment.
- A full-line comment begins with
;in the label column. MAC/65 also accepts*. - Accumulator-mode instructions take an explicit
A:ASL A,ROR A.
10 ;LIST#D:ADDTEST.ASM
20 RESULT = $CB
30 *=$4000
40 START LDA #5
50 CLC
60 ADC #3
70 STA RESULT
80 BRK
Line 10 shows a habit Matthew Ratcliff recommended in ANALOG: make the first line a comment holding the exact LIST command for the file. Later you can list line 10, cursor over the line number and semicolon, delete them, and press RETURN to save under the right name every time.
3. Editor commands
| Command | What it does |
|---|---|
NEW |
Clear the source |
NUM / NUM 100,10 |
Auto line numbering (start, step). RETURN on an empty line stops it |
REN / REN 100,10 |
Renumber |
DEL 50,100 |
Delete a range |
FIND/LDA/ , FIND/LDA/,A |
Find the first, or every, match. Any delimiter pair works |
REP/old/new/ , …/,A , …/xx,yy,Q |
Replace the first, all, or with a query in a line range |
LIST , LIST #P: , LIST #D:FILE.ASM,100,200 |
List to the screen, printer or disk. This is how you save source in the Assembler Editor |
ENTER #D:FILE.ASM , …,M |
Read listed source back, optionally merging |
PRINT |
Like LIST but without line numbers, so it can't be re-ENTERed |
SIZE |
Show source start, source end and top of RAM |
LOMEM addr |
Move the source buffer (must be the first command after power-up) |
ASM |
Assemble (see below) |
BUG |
Enter the debugger (Assembler Editor) |
DOS |
Go to DOS |
Device names take a # and no quotes: #D:, #D2:, #C:, #P:, and under Altirra #H:. In Altirra, H6: to H9: are aliases of H1: to H4: that also convert end-of-line characters (ATASCII $9B to and from CR/LF). LIST#H6:ADDTEST.ASM therefore leaves an ordinary text file on your PC that a cross-assembler such as ATasm can read.
4. Assembling
The general form is ASM source,listing,object. Any field can be left empty, but you must keep its comma:
ASM source in memory, listing to screen, object to memory
ASM ,#P: listing to the printer
ASM ,,#D:ADDTEST.OBJ object code to a disk file (binary-load format)
ASM #D:BIG.ASM,,#D:BIG.OBJ assemble from disk (needed for large programs)
The Assembler Editor needs several passes, so it can assemble from disk but not from cassette. Its listing always goes somewhere. When assembling to memory, first check SIZE. The object code must not overlap your source text or the symbol table, which grows upward from the end of the source. Ratcliff suggests *=$3400 as an origin for stand-alone programs, because it clears DOS.SYS and DUP.SYS in every Atari DOS through DOS XE and in SpartaDOS.
To make a disk file run automatically when it loads, add a RUNAD segment before assembling to disk:
90 *=$2E0
100 .WORD START
(Change the BRK to RTS for a program run from DOS.)
Directives
*= (origin), label = (equate), .BYTE (bytes and strings, e.g. .BYTE "HELLO",$9B), .DBYTE (high byte first), .WORD (low byte first), .OPT LIST/NOLIST/OBJ/NOOBJ/ERR/NOERR/EJECT/NOEJECT, .TITLE, .PAGE, .TAB, .IF and .END. In the cartridge, LABEL&255 gives the low byte of an address and LABEL/256 the high byte. Its arithmetic is evaluated strictly left to right, with no precedence.
5. The debugger
Type BUG and the prompt becomes DEBUG. All numbers are hex, with no $.
| Command | Example | Effect |
|---|---|---|
DR / CR |
CR<,1,2,,DE |
Display or change registers (A,X,Y,P,S; an empty field leaves a register alone) |
D |
D4000 , D4000,4010 |
Dump memory (8 bytes, or a range) |
C |
C00CB<08 , C4000<A9,05 |
Change memory. ,, skips a byte |
L |
L4000 , L4000,0 |
Disassemble |
A |
A then 4000<LDA #$05 |
One-line mini-assembler (here you must use $) |
M |
M0600<0700,0800 |
Move memory |
V |
V7000<7100,7123 |
Compare (verify) two blocks |
G |
G4000 |
Run until BRK (or BREAK) |
T |
T4000 |
Trace: run, printing each instruction and the registers |
S |
S4000, then S |
Single-step |
X |
X |
Back to the editor |
Try it with the program above: ASM, BUG, G4000. The debugger stops at the BRK and shows the registers, with A=08. D00CB,0 shows the result in memory. This is why tutorials of the period ended test programs with BRK instead of RTS.
6. What changes with MAC/65
MAC/65 keeps the cartridge's feel but changes some important details:
- Syntax checking as you type. Each line is checked on entry, and errors are shown with the cursor at the bad spot. The line is stored anyway, so ENTERing foreign source never loses text.
TEXTmode turns checking off for plain-text editing. - Tokenized storage. Lines are tokenized (roughly 60–80% smaller than ASCII), so
SAVE/LOADhandle the compact token files (.M65) andLIST/ENTERhandle text.ENTER #D:FILE,Aauto-numbers unnumbered text, which is useful for source from line-number-free assemblers. - No object code in memory unless you ask. You need
.OPT OBJbefore code that should be assembled into RAM. The cartridge does the opposite, which MAC/65's manual calls "a dangerous practice". - Operator precedence.
LDA #LABEL-3/256is[LABEL-3]/256to the cartridge butLABEL-[3/256]to MAC/65. Use<and>for low and high bytes, and[ ]for grouping. - More power. Macros (
.MACRO,%1,%$1),.INCLUDE,.LOCALwith?labels,.SBYTE,.CBYTE,.FLOAT,.SET, labels of up to 127 significant characters, and a cross-reference listing (ASM ,#P:,,#D:TEMP). - Extra commands:
BLOAD #D:OBJ,BSAVE #D:OBJ<5000,5100,CandDfor quick memory pokes and peeks,LOMEM,FIND, andCP/DOS. - Debugger. It depends on the version. Rev 1.2 has a
DDTcommand that enters the DDT ("Dunion Debugging Tool") package built into the MAC/65 cartridge. Tom Hudson, writing in 1984, described MAC/65 as coming with the BUG/65 debug package, which "doesn't recognize the BRK instruction". That's why ANALOG published its own HBUG for Boot Camp readers.
7. Moving period source to a modern assembler
LIST (not SAVE) the source to H6: or to a disk image, and convert ATASCII to ASCII if you used plain H:. Then assemble it with ATasm, which was designed to be "mostly Mac/65 compatible". It ignores line numbers, so period listings assemble as typed. Check the few known differences: * comment lines, unique macro names, and </> precedence. MADS needs more editing, because labels and instructions must move to column-based layout.
Troubleshooting
- The label column is wrong and nothing assembles. Check the spaces: one space then a label, or two spaces then the mnemonic.
- The source gets corrupted after
ASM. The object code was assembled over it. CheckSIZE, raise the origin, or assemble to disk. - MAC/65 "assembles" but nothing is in memory. Add
.OPT OBJ. - Mysterious values in expressions after switching tools. It's precedence. Add brackets.
Gnever returns. The code has no BRK, or loops forever. Press BREAK (on some programs only RESET will stop them).
Further reading
- The Atari Assembler, Don and Kurt Inman (Reston Publishing/Prentice-Hall, 1981). A tutorial built around the cartridge's Writer/Editor, Assembler and Debug modes.
- Assembly Language Programming for the Atari Computers, Mark Chasin (McGraw-Hill, 1984). Chapter 6 compares the Assembler Editor with AMAC, MAC/65, SYNASSEMBLER, MAE and Edit 6502.
- ANALOG's "Assembler/Editor Non-Tutorial" (Charles Bachand, 1981–82) and "Boot Camp" (Tom Hudson, from 1983), indexed on KSquiggle's site.
- Machine Language for Beginners, Richard Mansfield (COMPUTE! Books, 1983). The MAC/65 manual itself recommends it.
Credits
- The Assembler/Editor Reference, parts 1–2 (Matthew J.W. Ratcliff, A.N.A.L.O.G. #78–79, 1989) — ksquiggle, 1989
- Assembly Language Programming for the Atari Computers (Mark Chasin), ch. 6 — Assemblers for the ATARI — AtariArchives.org
- The Atari Assembler (Don & Kurt Inman, Reston/Prentice-Hall, 1981) — Atari8bit.net, 1981
- MAC/65 manual (OSS) — text edition and Reference Manual Rev 1.2 — Atari8bit.net
- comp.sys.atari.8bit FAQ (Michael Current) — Atari history timeline, 400/800-only software — Michael Current (comp.sys.atari.8bit FAQ)
- HBUG — Hudson's Debugging Utility (Tom Hudson, A.N.A.L.O.G. #18, 1984) — ksquiggle, 1984
- Altirra help — host device (H:) — Screenshot from Avery Lee's Altirra page, virtualdub.org
- ATasm manual (MAC/65 compatibility notes) — atari.miribilist.com
