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. TEXT mode turns checking off for plain-text editing.
  • Tokenized storage. Lines are tokenized (roughly 60–80% smaller than ASCII), so SAVE/LOAD handle the compact token files (.M65) and LIST/ENTER handle text. ENTER #D:FILE,A auto-numbers unnumbered text, which is useful for source from line-number-free assemblers.
  • No object code in memory unless you ask. You need .OPT OBJ before 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/256 is [LABEL-3]/256 to the cartridge but LABEL-[3/256] to MAC/65. Use < and > for low and high bytes, and [ ] for grouping.
  • More power. Macros (.MACRO, %1, %$1), .INCLUDE, .LOCAL with ? 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, C and D for quick memory pokes and peeks, LOMEM, FIND, and CP/DOS.
  • Debugger. It depends on the version. Rev 1.2 has a DDT command 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. Check SIZE, 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.
  • G never 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