ATAMON V1.3

Table of Contents

• ATAMON V1.3

  • Table of Contents

  • Foreword

  • What is ATAMON?

• Technical Documentation

  • Machine Language Monitor for the Atari 800XL

  • 1. General Overview

  • 2. Memory Layout

  • 3. Startup Mechanism

    • Register Save Area ($401C)

  • 4. Main Command Loop

    • Command Prompt and Register Display

  • 5. How to Load Your Program into ATAMON

    • The Double-Agent Plan

    • Setting Breakpoints in Your Program

  • 6. Command Reference

    • Syntax Conventions

    • G [aaaa] — Go (Execute)

    • M aaaa — Memory (Display Memory)

    • E ssss — E (Read a Disk Sector)

    • D aaaa[,bbbb] — Disassemble

    • L aaaa,bbbb,xx — Locate Non-Matching (Find Non-Matching Bytes)

    • W ssss — Write (Write a Disk Sector)

    • V aaaa,bbbb,cccc — Verify (Compare Memory)

    • F aaaa,bbbb,bb — Fill

    • T aaaa,bbbb,cccc — Transfer (Copy Memory)

    • H aaaa,bbbb,DsearchD — Hunt (Search Memory)

    • S aaaa — Scan (Real-Time Binary Monitor)

    • C aaaa,bbbbbbbb — Code (Write Binary Bytes to Memory)

    • P [E|T] — Printer (Printer Control)

    • R — Registers (Display Registers)

    • X — eXit (Quit to DOS)

    • Z nn,cc[,aaaa,llll] — IOCB (CIO Channel Operation)

      • The CIO System in Brief

      • IOCB Channels

      • Z Syntax

    • I aaaa,DdataD — Input String (Write Text to Memory)

    • # — Decimal → Hexadecimal Conversion

    • $ — Hexadecimal → Decimal Conversion

    • % — Binary Input

    • ; aaaa BB BB BB BB XXXXXXXX — Set (Load All Registers at Once)

    • ! aaaa — Binary (Hexadecimal → Binary Conversion)

    • * OP aaaa,bbbb — Arithmetic (Calculator)

    • : aaaa bb bb bb bb bb bb bb bb — Enter (Write Bytes to Memory)

    • , aaaa bb [bb ...] — Enter with Disassembly

  • 7. Internal Variables (Zero Page)

  • 8. Main Subroutines

  • 9. Atari System Usage

  • 10. Internal Data Tables

    • Banner and Register Format ($4F44)

    • Hex Digit + Command Table ($4F8D)

    • Dispatch Table ($4FC8)

    • Built-in Disassembler Tables ($4FF9+)

  • 11. How to Use ATAMON

    • Starting Up

    • Special Keys

    • Typical Startup Display

    • Sample Session

  • 12. Historical Notes

  • 13. Technical Notes on Disassembly

    • Known 6502 Illegal Opcodes

    • JMP Indirect Bug

  • Annex A — Zero Page Glossary ($00–$FF)

    • Atari OS Variables (Reserved by the System)

    • Variables Used by ATAMON

  • Annex B — The 56 Official 6502 Mnemonics

    • Load / Store

    • Register Transfers

    • Stack

    • Arithmetic

    • Increment / Decrement

    • Logical Operations

    • Shifts and Rotations

    • Comparisons

    • Conditional Branches

    • Jumps and Calls

    • Software Interrupt

    • Flag Operations

    • Miscellaneous

  • Annex C — Illegal / Undocumented 6502 Opcodes

    • Fatal Instructions

    • Combined Read-Modify-Write Instructions

    • Combined Load / Store

    • Accumulator Instructions

    • Unstable Memory Instructions (depend on addr_hi)

    • Illegal NOPs (multi-byte, no effect)

  • Annex D — Known Atari Labels

    • Zero Page — OS Variables ($00–$FF)

    • Page 2 — Interrupt Vectors ($0200–$02FF)

    • Page 3 — SIO DCB ($0300–$035F)

    • Hardware Registers — GTIA ($D000)

    • Hardware Registers — POKEY ($D200)

    • Hardware Registers — PIA ($D300)

    • Hardware Registers — ANTIC ($D400)

    • OS ROM Entry Points ($E4xx)

    • Math ROM ($D8xx)

  • Annex E — Atari 800XL Hardware Registers — Quick Reference

    • GTIA — Graphic Television Interface Adaptor ($D000–$D01F)

    • POKEY — Potentiometer and Keyboard ($D200–$D20F)

    • PIA — Peripheral Interface Adaptor ($D300–$D303)

    • ANTIC — Alphanumeric Television Interface Circuit ($D400–$D40F)

  • Fixing the C Command Bug (Patch)

    • The Bug

    • The Fix

    • Applying the Patch

  • References

    • 6502 Processor

    • Atari 800XL Documentation

    • AtariWiki

    • .PRO Disk Format

    • Emulator Used for Testing

Foreword

The documentation for ATAMON (ATAri MONitor) has been missing for over 40 years.

What you are reading is an unofficial documentation, the result of hours of work, testing, decompilation and writing from the disassembled code of ATAMON.

I hope you enjoy it ;-)

Atarinside — March 2026

The program can be found here: https://www.atarinside.com/blog/index.php/atarinside-items/atamon/

What is ATAMON?

You have just loaded ATAMON, ATARI's machine language monitor. But what exactly does a monitor do?

Your Atari 800XL runs on a processor — the 6502 — which executes thousands of instructions per second. These instructions — called "machine language" — are stored in memory as numbers. ATAMON is the tool that lets you view, modify and execute these instructions directly, without going through an intermediate language like BASIC.

Concretely, ATAMON lets you:

• Look inside memory: display any area of your Atari's RAM, byte by byte, to see what it contains.

• Modify memory: change values directly, fix a bug in a program, or customise a game to your liking.

• Disassemble a program: ATAMON translates raw machine language into readable mnemonics (such as LDA, JMP, STA…), allowing you to understand how a program works.

• Execute and debug: launch a program and regain control at each BRK breakpoint, observing the processor state — essential for tracking down a bug.

• Save sectors: read and rewrite disk sectors directly (via the E and W commands).

• Calculate: perform additions, subtractions, logical AND, logical OR directly in hexadecimal or binary.

Who is it for? ATAMON is aimed at programmers, enthusiasts who wish to understand the inner workings of their Atari, or anyone who wants to explore and modify machine language programs. No additional hardware is required: ATAMON runs entirely on your Atari, with your standard disk drive.

How to start? From the Atari DOS menu, select L. BINARY LOAD, type D:ATAMON and press Enter. The program installs itself in memory starting at address $4000, displays its banner, and the Atari cursor indicates it is ready to receive a command. All commands are a single letter — fast and efficient.

Technical Documentation

Machine Language Monitor for the Atari 800XL

Source file: Atamon - D7 - DXG 5724.PRO → ATAMON Identification: *** ATAMON V1.3 - (c) 1983 by ATARI *** Type: 6502 machine language monitor / debugger Size: 4,404 bytes Format: Atari XEX (multiple segments) Load address: $4000 Run address (RUNAD): $4000 Source language: 6502 assembly Publisher: Atari Deutschland GmbH (Atari Germany) — ATAMON is an Atari Germany product, identified by catalogue number DXG 5724 Author: Not identified — the binary contains no programmer name, only (c) 1983 by ATARI Probable assembly tool: Atari Macro Assembler or MAC/65 (OSS) — inferred from the structure of 256-byte XEX segments (252 bytes of code + 4-byte header), a characteristic output format of native Atari assemblers from 1983

1. General Overview

ATAMON is a professional machine language monitor developed by ATARI in 1983. It allows a programmer to:

• Examine and modify RAM

• Display and modify 6502 registers (program counter, stack pointer, accumulator, X, Y, flags)

• Disassemble 6502 code directly in memory

• Execute code and regain control at each BRK breakpoint

• Read and rewrite disk sectors

• Verify and transfer memory regions

• Perform hexadecimal calculations

It belongs to the family of machine language monitors that accompanied 8-bit computers of the era on many platforms.

2. Memory Layout

xxxxxxxxxx
Address     Contents
---------   --------------------------------
$4000       Main entry point (RUNAD)
$4000-$52B1 ATAMON code and data
$4F3C-$4F42 CPU register save area
$4E3C       Keyboard input buffer (command line)
$4F44       ASCII banner + register display format
$4F8D       Hex digit table + command characters
$4F9D       Command dispatch table
$4FC8       Handler address table (vectors)
$4FF9+      Internal 6502 disassembler tables

Memory footprint: approximately 4.5 KB from $4000 to $52B1. ATAMON also sets MEMLO = $5300 to protect its code.

3. Startup Mechanism

The entry point at $4000 uses a classic technique: the BRK vector ($0206–$0207).

xxxxxxxxxx
$4000  LDA #$40         ; Install BRK handler
$4002  STA $0207        ; VBREAK hi = $40
$4005  LDA #$0B
$4007  STA $0206        ; VBREAK lo = $0B  →  handler at $400B
$400A  BRK              ; Intentionally trigger BRK
; === The 6502 pushes (current address + 2) and flags onto stack, jumps via $0206 ===
$400B  LDA #$40         ; Reconfigure VBREAK for future use
$400D  STA $0207
$4010  LDA #$1A
$4012  STA $0206        ; New VBREAK = $401A
$4015  LDA #$43         ; 'C' = "entry via startup" indicator
$4017  JMP $401C        ; → Save CPU state

Why this technique? The BRK instruction automatically pushes the address of the next instruction (current address + 2) and the status register onto the stack. ATAMON then retrieves these values to build a complete snapshot of the processor state at the time of entry into the monitor.

Register Save Area ($401C)

xxxxxxxxxx
$401C  STA $E4          ; Save entry indicator (passed by caller)
$401E  PLA              ; Retrieve A (pushed by OS handler before BRK)
$401F  STA $4F3D        ; Save A
$4022  STY $4F3F        ; Save Y
$4025  STX $4F3E        ; Save X
$4028  PLA              ; Retrieve P (flags, from BRK stack)
$4029  STA $4F40        ; Save P
$402C  CLC
$402F  PLA              ; Retrieve PCL (low address byte, from BRK stack)
$4030  ADC #$FF         ; Subtract 1 (16-bit: BRK pushes addr+1, we return to real address)
$4032  STA $4F41        ; Save adjusted PCL
$4035  PLA              ; Retrieve PCH (high address byte, from BRK stack)
$4036  ADC #$FF         ; Continue 16-bit subtraction with carry
$4038  STA $4F42        ; Save adjusted PCH
$403B  TSX
$403C  STX $4F3C        ; Save SP
$403F  LDX #$FD
$4041  TXS              ; Reset stack to $FD

Note on the entry mechanism: The Atari OS handler (ROM IRQ) pushes register A via PHA before calling the VBREAK vector. This is why SAVE_CPU performs 4 successive PLAs (A, P, PCL, PCH) even though the BRK instruction only pushes 3 (P, PCL, PCH).

Register save area ($4F3C–$4F42):

xxxxxxxxxx
$4F3C  SP  Stack pointer
$4F3D  A   Accumulator
$4F3E  X   X register
$4F3F  Y   Y register
$4F40  P   Status register (flags NV\BDIZC)
$4F41  PCL Low byte of next instruction address (adjusted -1)
$4F42  PCH High byte of next instruction address

This layout is confirmed by the G (Go) handler: LDA $4F3D restores A, LDA $4F40; PHA; PLP restores P, JMP ($4F41) jumps to address $4F42:$4F41.

4. Main Command Loop

After initialisation, ATAMON displays its banner and enters the command loop ($4064):

xxxxxxxxxx
1. Reset stack to $FD
2. Clear input buffer ($4E3C ← $9B)
3. Open channel E: (screen editor) via CIO
4. Read a line via CIO (IOCB 0)
5. Find the first non-space character
6. Look up this character in table $4F9D
7. If found → load handler address from $4FC8/$4FC9
8. Execute handler via indirect RTS (push hi-1 / lo-1, RTS)
9. Return to step 1

Command Prompt and Register Display

ATAMON does not display an explicit prompt: the input prompt is the Atari screen editor cursor (blinking inverse-video block), managed automatically by the OS. When this cursor is visible, ATAMON is waiting for a command.

The *R, *B, *C headers are ATAMON display prefixes, not the prompt. The asterisk * (code $2A) is emitted by ATAMON before displaying registers, followed by a letter indicating the entry context:

• *C — entry via startup or G

• *R — R command

• *B — return on BREAK (interruption of a program)

Example register display (after R command or a BRK):

xxxxxxxxxx
*R
  PC  SP AC XR YR NV\BDIZC
; 400B FB 0B 20 01 00110001

The value line always begins with ;. Meaning of each field:

This line updates automatically after each program return (following a BRK or G), to reflect the actual processor state at that instant.

5. How to Load Your Program into ATAMON

The Atari stores the auto-run address of the last loaded program in a specific memory location at address $02E0 (the system vector called RUNAD).

If you load your game, its start address will be stored at $02E0. But if you then load ATAMON right after, ATAMON's start address ($4000) will overwrite your game's!

To work around this and use ATAMON as a detective tool, we reverse the loading order using another DOS menu option (M).

The Double-Agent Plan

Step 1: Install the monitor "undercover"

1. From the DOS menu, use L to load ATAMON.

2. ATAMON displays on screen. Type the command X (eXit).

3. You return to the DOS menu, but ATAMON remains hidden in memory (from $4000 onwards).

Step 2: Load your game silently

1. Back in DOS, use L again to load your program, adding /N (no space after the filename) — example: MYPROG.BIN/N.

2. The game loads into memory and the OS writes its start address to $02E0. Because we used /N, DOS does not jump to that address, does not execute the loaded program, and keeps you in the menu.

Step 3: Wake ATAMON up

1. In the DOS menu, choose option M (Run at address).

2. Type 4000 (the address where ATAMON is sleeping) and press Enter.

3. The ATAMON banner appears — you are back in the monitor!

Step 4: Read the magic address

1. At the ATAMON prompt, display memory at address $02E0 by typing:

xxxxxxxxxx
Input:
M 02E0

2. Press BREAK immediately to stop the scrolling.

3. Look at the first two bytes of the displayed line.

Attention — Little Endian: the Atari stores addresses "backwards" (low byte first, then high byte).

• If ATAMON displays :02E0 00 50 ..., your program's address is $5000.

• If it displays :02E0 00 2A ..., the address is $2A00.

That is it! You just need to use the G command followed by the discovered address (e.g. G 5000) to launch your program, knowing that ATAMON is ready to intercept any crash or breakpoint (BRK).

Setting Breakpoints in Your Program

Warning: ATAMON does not have a guaranteed asynchronous interrupt function.

The only reliable method to hand control back to ATAMON in the middle of a program is to deliberately insert a software breakpoint:

1. Temporarily replace one byte of your program with the BRK instruction (hex code $00).

2. When the processor executes that $00, it will trigger a software interrupt.

3. ATAMON has redirected the system interrupt vector (VBREAK at $0206–$0207) when it loaded.

4. The processor will jump directly into ATAMON, which will save all your registers (A, X, Y, PC...) and display its prompt with *B to signal that it has intercepted a BRK.

In summary: if your program is an infinite loop with no BRK instruction, the BREAK key will not save you (unless your code calls the OS keyboard routines). You will need a Reset! Always remember to place your $00 breakpoints strategically before launching your code with G.

6. Command Reference

The command table is stored from $4F9D. Commands are entered in uppercase. When a command takes multiple arguments, they are separated by commas (no space between arguments). A space is accepted before the first argument.

Syntax Conventions

• aaaa = 16-bit address in hexadecimal (e.g. 4000)

• bb = 8-bit byte in hexadecimal (e.g. FF)

• [...] = optional argument

G [aaaa] — Go (Execute)

Starts execution at address aaaa. Without argument: resumes from the saved program counter (PC register). Restores all saved CPU registers before performing JMP aaaa.

Warning: G aaaa jumps directly to the given address. If that address does not contain a valid program (e.g. uninitialised RAM), the 6502 will execute garbage and the system will crash. G alone is safe: it resumes from the PC saved at the last BRK.

First use after startup: the saved PC is $400B. Typing G alone re-executes ATAMON startup.

Examples:

​x

Input:
G ; At first launch, re-executes ATAMON startup:

*** ATAMON V1.3 - (c) 1983 by ATARI  ***
*C
  PC  SP AC XR YR NV\BDIZC
; 400B FD 00 00 00 00110000

; After a BRK in your own program, resumes from the saved PC

Input:
G 4000 ; Starts execution at $4000 — ATAMON disappears while your program runs.
; It only regains control if the program executes a BRK (breakpoint).

M aaaa — Memory (Display Memory)

Displays memory starting at aaaa, 8 bytes per line in hex. Scrolls indefinitely — press BREAK to stop.

Each line: : + address + 8 hex bytes + ATASCII column on the right.

Example:

xxxxxxxxxx

Input:
M 4000

Result (scrolls endlessly — press BREAK to stop):
:4000  A9 40 8D 07 02 A9 0B 8D  ©@♦ ©.♦
:4008  06 02 A9 43 4C 1C 40 48  . ©CL @H
:4010  68 48 8C 3F 4F A8 B9 40  hH♦?O¨¹@
; ... (continues automatically)

E ssss[,aaaa[,nn]] — E (Read a Disk Sector)

Reads disk sector ssss (hex) from D1: into the buffer at aaaa (default: $0680). Displays OK on success.

Optional arguments:

• aaaa: destination buffer address (default: $0680)

• nn: number of consecutive sectors to read (default: 01) — buffer advances by $80 (128 bytes) per sector

Caution: ssss is a sector number, not a memory address. A single-density Atari disk (720 sectors) has sector numbers $0001 to $02D0. Exceeding this range causes an I/O error.

To view the loaded sector content: type M 0680 — ATAMON displays the bytes from $0680 scrolling (press BREAK to stop after seeing the first 128 bytes of the sector).

xxxxxxxxxx

Input:
E 0168 ; Read sector 360 ($0168) = VTOC sector of DOS 2.x
Result:
OK
; ATAMON displays "OK" — the sector is now at $0680

Input:
E 0001,0700
Result:
OK
; Sector 1 loaded at $0700 instead of default $0680

Input:
E 0001,0700,02
Result:
OK
; Sector 1 → $0700, sector 2 → $0780

Input:
E 0001
Result on error:
I/O ERROR #138

D aaaa[,bbbb] — Disassemble

Disassembles 6502 code from aaaa and displays the mnemonics. Uses the internal tables at $4FF9 containing the 56 6502 mnemonics and addressing mode decoding information.

Important: the end address bbbb is syntactically accepted but ignored — ATAMON disassembles indefinitely, wraps $FFFF→$0000. Press BREAK to stop.

xxxxxxxxxx

Input:
D 4000,400C

Result (press BREAK to stop):
4000  A9 40     LDA #$40
4002  8D 07 02  STA $0207
4005  A9 0B     LDA #$0B
4007  8D 06 02  STA $0206
400A  A9 43     LDA #$43
400C  4C 1C 40  JMP $401C

Each line shows: address, raw bytes in memory, then the disassembled instruction.

L aaaa,bbbb,xx — Locate Non-Matching (Find Non-Matching Bytes)

Scans aaaa–bbbb and displays addresses where the byte is different from xx.

In practice: L identifies bytes that "do not match" a reference value. Useful for quickly spotting differences between two regions after a copy, or finding modified bytes in a program.

L alone → error ? — three arguments required.

Note: ATAMON has no file load command. Programs must be loaded from Atari DOS (option L. BINARY LOAD) before launching ATAMON.

xxxxxxxxxx

Input:
F 6000,60FF,EA ; (fills $6000–$60FF with $EA)
: 6000 A9 FF 8D 00 D0 4C 00 40 ; (modifies some bytes at $6000)
L 6000,60FF,EA ; Scans $6000–$60FF and displays addresses where byte ≠ $EA

Result (7 addresses per line — press BREAK to stop, displays *B):
6000  6001  6002  6003  6004  6005  6006
6007
*B
; → addresses $6000–$6007 contain bytes ≠ $EA
; Addresses where the byte equals exactly $EA are NOT displayed

W ssss[,aaaa[,nn]] — Write (Write a Disk Sector)

Writes the buffer at aaaa (default: $0680) to disk sector ssss (hex).

Optional arguments: same as E — source buffer address and sector count.

Caution: overwrites the sector on disk directly — irreversible. ssss is a sector number in hex (1 to $02D0 = 720 for a single-density disk).

E and W work in tandem: E to read a sector, modify with M or :, then W to rewrite.

xxxxxxxxxx

Input:
E 0001 ; 1. Read sector 1 into buffer ($0680)

; (optionally modify the buffer with : 0680 A9 FF ...)

Input:
W 0001 ; 2. Rewrite the buffer to sector 1

Result: OK
; On error: I/O ERROR #xxx

V aaaa,bbbb,cccc — Verify (Compare Memory)

Compares aaaa–bbbb with the region at cccc (memory to memory). Reports addresses where bytes differ. No changes made.

Useful to verify that a copy (made with T) matches the original, or to compare two versions of a program.

xxxxxxxxxx

Input:
T 6000,600F,6100 ; (copy $6000–$600F to $6100)
V 6000,600F,6100 ; Compare $6000–$600F with $6100–$610F

Result if all matches:
OK

; To see differences, modify a byte before comparing:

: 6100 FF FF 00 00 00 00 00 00

V 6000,600F,6100 ; $6100 and $6101 were modified → ATAMON reports $6000 and $6001

Result (7 addresses per line):
6000  6001
; Only SOURCE addresses where bytes differ are displayed — not the values.

Note: if the destination region is uninitialised (arbitrary RAM), almost all addresses in the range will appear in the result.

F aaaa,bbbb,bb — Fill

Fills aaaa–bbbb with byte bb. Displays OK.

Safe zone: use $6000+ (ATAMON occupies $4000–$52B1).

xxxxxxxxxx

Input:
F 6000,60FF,EA
Result:
OK
; ATAMON displays "OK" then returns to prompt
; $6000 to $60FF (256 bytes) now contains $EA (NOP opcode)
; Useful to "clean" a region or write NOPs before patching code

; To verify the NOPs were written:
M 6000
Result:
:6000  EA EA EA EA EA EA EA EA  nnnnnnn
:6008  EA EA EA EA EA EA EA EA  nnnnnnn
; ... (press BREAK to stop)
; Right column = ATASCII of $EA (character 'n' in inverse ATASCII)

T aaaa,bbbb,cccc — Transfer (Copy Memory)

Copies aaaa–bbbb to cccc (memory to memory). Performs byte-by-byte verification and reports differences. Displays OK on success.

Overlapping regions: if source and destination overlap, a naive start-to-end copy would overwrite unread source bytes. ATAMON avoids this: if destination is before the source it copies left-to-right; if destination is after the source (right overlap) it copies right-to-left. The result is always correct regardless of configuration.

Safe zone: ATAMON occupies $4000–$52B1. For tests, use a region beyond $5300 (e.g. $6000–$7FFF, free RAM).

xxxxxxxxxx

Input:
T 6000,60FF,6100
Result: OK

T 6000,6008,6004
Result: (silent — overlap handled)

H aaaa,bbbb,DsearchD — Hunt (Search Memory)

Searches aaaa–bbbb for byte sequence DsearchD. Displays addresses found, then OK.

D = any delimiter character. Data: hex pairs or 'string' in single quotes. Without internal single quotes, letters are interpreted as hex digits — AT = A (valid hex) + T (invalid) → corrupted result.

Search only — no replace. Three arguments minimum required (H or H aaaa,bbbb → ?).

xxxxxxxxxx

Input:
H 4000,52B0,"'ATARI'"
Result:
4D99  4E4A  4F62
OK

Input:
H 4000,52B0,"4154415249"
Result:
4D99  4F62
OK
; Hex form gives 2 results (no self-match); quoted form gives 3 (input buffer match).

S aaaa — Scan (Real-Time Binary Monitor)

Displays 4 bytes at aaaa as binary, refreshing the same line continuously. Press BREAK to stop.

S alone → ?. No single-step: insert BRK instructions manually.

Example with a fixed address:

xxxxxxxxxx

Input:
S 4000

Result (same line refreshes continuously):
10101001 01000000 10001101 00000111
; The 4 bytes at $4000–$4003 displayed and updated continuously
; Press BREAK to return to prompt

Example with a real-time hardware register:

xxxxxxxxxx

Input:
S 0014

Result (line changes visibly):
00000000 00000001 01001100 00000000
00000000 00000001 01001101 00000000
; The byte at $0016 increments continuously — proof the Atari is running
; Press BREAK to stop

Particularly useful for monitoring hardware registers (POKEY, GTIA, ANTIC, RTCLOK clock) that change in real time, or observing a variable evolve during program execution.

C aaaa,bbbbbbbb — Code (Write Binary Bytes to Memory)

Writes bytes at aaaa. Each byte = 8 binary digits (0 or 1), separated by commas.

C alone → ?

Note: Buggy in original V1.3 — writes $2C (comma) instead of parsing binary arguments and returns ?. The examples below describe the behaviour of the patched version only (Atamon - D7 - DXG 5724-Patched Atarinside.atr). See Fixing the C Command Bug.

xxxxxxxxxx

Input:
C 6000,10110001 ; Writes $B1 (binary 10110001) at $6000

Result:
; (no display — the Atari cursor reappears)

; Verification:

Input:
M 6000
Result:
:6000  B1 xx xx xx xx xx xx xx  [...]
; → $B1 correctly written at $6000 (BREAK to stop scrolling)

Multiple bytes:

xxxxxxxxxx

Input:
C 6000,01001100,00000000,01100000 ; Writes $4C $00 $60 at $6000 (= JMP $6000 in machine language)

P [E|T] — Printer (Printer Control)

Controls the printer channel (IOCB 6, device P1:).

• P alone: closes channel → displays AUS (German: off)

• P E: opens echo mode → displays EIN (German: on)

• P T: data transfer (untested)

xxxxxxxxxx

Input:
P
Result:
P    AUS
; Printer channel currently closed (AUS = "aus" = "off" in German)

Input:
P E
Result:
EIN
; Printer echo enabled (EIN = "ein" = "on" in German)
; All ATAMON output will also be printed

Input:
P ; (to disable echo)
Result:
P    AUS

Note: this command is useful if you have a printer connected to your Atari. Without a printer, P E will cause an I/O error.

R — Registers (Display Registers)

Displays all saved CPU registers. Display only — no modification.

To modify registers, use the ; command (full load) or write directly to memory at $4F3C–$4F42.

xxxxxxxxxx

Input:
R
Result:
*R
  PC  SP AC XR YR NV\BDIZC
; 4000 FD 00 00 00 00110000

X — eXit (Quit to DOS)

Returns to Atari DOS via JMP DOSVEC ($000A).

xxxxxxxxxx

Input:
X ; ATAMON exits — the Atari DOS screen reappears

Z nn,cc[,aaaa,llll] — IOCB (CIO Channel Operation)

Executes an OS I/O operation on a CIO channel.

The CIO System in Brief

xxxxxxxxxx
Your program
      | (via IOCB)
CIO -- Central I/O         <- single entry point
      | (via ZIOCB)
Device handlers
      | (via DCB)
SIO -- Serial I/O

The CIO provides a single entry point ($E456) for all devices: whether writing to the screen, reading the keyboard or accessing a disk, it is always the same OS routine you call. The device handler (a specific ROM or RAM routine) does the real work.

ROM-resident handlers (always available, loaded automatically at startup):

Non-resident handlers (loaded into RAM at boot by DOS or a peripheral ROM):

These non-resident handlers are added to the handler table ($031A) at startup as soon as the corresponding device is connected and powered on. If the device is absent, the handler is not loaded and any attempt to access D:, R: or T: via CIO returns an "unknown device" error.

IOCB Channels

Channels 1 to 5 have no fixed assignment — by design. Non-resident handlers (D:, R:, T:) do not open on a dedicated channel: the program freely chooses which channel to use for each device. For example, a program can open D:FILE.DAT on channel 1 and R1: (serial port) on channel 2 simultaneously. If BASIC is active, avoid using channels 6 and 7.

A record is a byte sequence terminated by ATASCII $9B. GET RECORD reads up to the next $9B; PUT RECORD writes and appends $9B at the end.

Z Syntax

• nn = channel offset (2 hex digits): 00 = channel 0, 10 = channel 1… 70 = channel 7

• cc = CIO command (2 hex digits)

• aaaa = buffer address in memory (4 digits, optional depending on command)

• llll = buffer length in bytes (4 digits, optional)

Z alone or Z nn alone → ? — cc is required.

Z copies the current channel IOCB, replaces the supplied fields (command, address, length), calls CIO, then rewrites the modified IOCB. No result is displayed — the effect is the output of the CIO operation itself.

Example — display text on screen via PUT RECORD on channel 0 (always open on E:):

xxxxxxxxxx
; Step 1: write "ATARI!!" + $9B (ATASCII end-of-line) at $6000

Input:
: 6000 41 54 41 52 49 21 21 9B

; Step 2: send 8 bytes from $6000 to screen via CIO

Input:
Z 00,09,6000,0008

Result:
ATARI!!
; → text displayed directly, Atari cursor reappears

To inspect the raw content of an IOCB, use M 0340 (channel 0) or M 0350 (channel 1).

I aaaa,DdataD — Input String (Write Text to Memory)

Writes text or binary data to memory at aaaa.

D = any delimiter (", /...). No space between comma and delimiter.

Inside the data:

• Hex bytes: 2-digit pairs (e.g. 9B)

• Literal string: 'text' (single pair of quotes — 'HELLO' not 'H'E'L'L'O')

xxxxxxxxxx

Input:
I 6000,"'HELLO'9B"
M 6000
Result:
:6000  48 45 4C 4C 4F 9B xx xx

Input:
I 6010,/FF 00 4C 00 40/
M 6010
Result:
:6010  FF 00 4C 00 40 xx xx xx

Input:
I 6020,"'ATARI'9B" ; ATASCII string + end-of-line byte
M 6020
Result:
:6020  41 54 41 52 49 9B xx xx

This command is particularly useful for writing error messages, ATASCII strings, or code patches directly into memory.

# — Decimal to Hexadecimal Conversion

Interprets the argument as a decimal value and displays its hexadecimal equivalent.

Useful when you know an address or value in decimal and want to know its hex equivalent before using it in another command.

xxxxxxxxxx

Input:
# 4000
Result:
# 4000 = 0FA0
; 4000 in decimal = $0FA0 in hexadecimal

Input:
# 255
Result:
# 255 = 00FF
; 255 in decimal = $FF in hexadecimal

$ — Hexadecimal to Decimal Conversion

Interprets the argument as a hexadecimal value and displays its decimal equivalent (complement of #).

xxxxxxxxxx

Input:
$ 1638
Result:
$ 1638 = 5688
; $1638 in hexadecimal = 5688 in decimal

Input:
$ 00FF
Result:
$ 00FF = 0255
; $FF = 255 in decimal — ATAMON requires exactly 4 hex digits
; $ FF (only 2 digits) → error ?

Important: $ requires exactly 4 hexadecimal digits. Use $ 00FF not $ FF.

% — Binary Input

Enters a value as 8 binary digits (0 and 1) and displays it in hexadecimal.

Useful for working directly with processor flags or any register whose bits you want to control individually — more readable than a hex byte for this type of manipulation.

xxxxxxxxxx

Input:
% 11001000
Result: C8
; $C8 = hexadecimal value of 11001000 binary (= 200 in decimal)

Input:
% 00110000
Result: 30
; $30 = flags I+B active (typical state at startup)

; aaaa BB BB BB BB XXXXXXXX — Set (Load All Registers at Once)

Loads all CPU registers in a single command line. Syntax: ; PCHL SP AC XR YR XXXXXXXX

• PCHL : 4 hex digits = program counter address (e.g. 5000)

• SP : stack pointer (e.g. FD)

• AC : accumulator

• XR : X register

• YR : Y register

• XXXXXXXX : 8 binary bits = P flags in order N V \ B D I Z C

Useful for restoring a precise execution context in one operation, e.g. to resume debugging a program exactly in the state it stopped.

Flag bits (left to right):

Example: 00110100 = bits N=0, V=0, \=1, B=1, D=0, I=1, Z=0, C=0 — typical state at startup (I=1: interrupts disabled).

xxxxxxxxxx

Input:
; 5000 FD 00 00 00 00110100

Result: ATAMON overwrites the typed line in place with the `;` format, without adding a new line.
The displayed content is identical to the input — the command appears silent.
; 5000 FD 00 00 00 00110100

Verification:

Input:
R
Result:
*R
  PC  SP AC XR YR NV\BDIZC
; 5000 FD 00 00 00 00110100
; → PC correctly at $5000, flags identical to those entered

! aaaa — Binary (Hexadecimal to Binary Conversion)

Converts hex aaaa to 16-bit binary and displays it. Does not read memory — converts the argument itself.

Format: ! aaaa = bbbbbbbb bbbbbbbb (high byte then low byte).

Useful for visualising the individual bits of a value (hardware register read beforehand, operation result, flag value…).

xxxxxxxxxx

Input:
! 4000
Result: ! 4000 = 01000000 00000000

Input:
! 00FF
Result: ! 00FF = 00000000 11111111

Input:
! D01F ; Convert $D01F (CONSOL register address) — to inspect a hardware register,
; read its value with M first, then convert with !
Result: ! D01F = 11010000 00011111

* OP aaaa,bbbb — Arithmetic (Calculator)

Arithmetic/logical operation on two 16-bit values. Result: RRRR C=b.

Operators: + - A (AND) O (OR) E (EOR/XOR).

* + 4000 alone → ? — both operands required.

xxxxxxxxxx

Input:
* + 4000,0100
Result: * + 4000,0100 = 4100  C= 0

Input:
* - 5000,0200
Result: * - 5000,0200 = 4E00  C= 1
; On the 6502, carry is inverted for subtraction: C=1 = no borrow (result ≥ 0), C=0 = borrow (negative result). The opposite of addition.

Input:
* A FF00,0FF0
Result: * A FF00,0FF0 = 0F00

Input:
* O 4000,0001
Result: * O 4000,0001 = 4001

Useful for calculating addresses, offsets or verifying memory ranges without leaving the monitor.

: aaaa bb bb bb bb bb bb bb bb — Enter (Write Bytes to Memory)

Writes 8 hex bytes at aaaa, displays the line, proposes next address. BREAK to return.

: aaaa alone → nothing.

xxxxxxxxxx

Input:
: 6000 A9 FF 8D 00 D0 4C 00 40
Result:
:6000  A9 FF 8D 00 D0 4C 00 40  )  PL @
:6008
; ATAMON proposes next address — type 8 new bytes or press BREAK to return to prompt

To enter a large region, continue line by line: each ENTER advances 8 bytes. To enter fewer than 8 bytes, use the I command.

Limitation: : verifies each byte after writing by reading the address back. This verification fails for hardware registers (POKEY $D200–$D20F, GTIA $D000–$D01F, ANTIC $D400–$D40F, PIA $D300–$D30F) because read and write addresses map to different physical registers. To write to hardware, store machine code in RAM and run it with G.

, aaaa bb [bb ...] — Enter with Disassembly

Writes hex bytes at aaaa and displays 6502 disassembly. Number of bytes per line is free. BREAK to return.

xxxxxxxxxx

Input:
, 6000 A9 00
Result:
, 6000 A9 00           LDA #$00
, 6002
; ATAMON displays bytes + disassembly, then proposes continuation with `,`
; Continue by typing the next bytes, BREAK to return to prompt

Input:
, 6002 4C 00 60
Result:
, 6002 4C 00 60        JMP $6000
, 6005
; 3 bytes written — JMP $6000 (jump to $6000)
; Continue or press BREAK

Ideal for entering assembly code and immediately verifying that the opcodes are correct.

7. Internal Variables (Zero Page)

8. Main Subroutines

9. Atari System Usage

ATAMON uses the following OS services:

IOCBs used:

• IOCB 0 ($0340): Main channel to E: (editor/screen) for all user I/O.

• The IOCB is configured dynamically by SET_FNAME / SET_BUFADDR / DO_CIO.

DCB structure for disk access ($0300-$030B):

• $0300 DDEVIC = $31 ('1') — disk device D1:

• $0301 DUNIT = 1

• $0302 DCOMND = SIO command ('R'=$52 read, 'W'=$57 write)

• $0303 DSTATS = direction ($40 = read, $80 = write)

• $0304-$0305 DBUFLO/HI = buffer address

• $030A-$030B DAUX1/2 = sector number

10. Internal Data Tables

Banner and Register Format ($4F44)

The string stored in memory is:

xxxxxxxxxx
*** ATAMON V1.3 - (c) 1983 by ATARI  ***E:P1:   PC  SP AC XR YR NV\BDIZC<$9B>

ATAMON points to the PC SP AC XR YR NV\BDIZC portion (at $4F71) to display the column header. The screen output (40 columns) is:

xxxxxxxxxx
*** ATAMON V1.3 - (c) 1983 by ATARI  ***
     PC  SP AC XR YR NV\BDIZC
; 4000 FD 00 00 00 00110000

Hex Digit + Command Table ($4F8D)

xxxxxxxxxx
$4F8D  "0123456789ABCDEF"   <- hex digits (index 0-15)
$4F9D  "RX;GM:EWFVTH#$%!I*PCSD,LZ"  <- command characters

Dispatch Table ($4FC8)

Byte pairs (address - 1) (lo, hi) for each command handler. The dispatch uses the RTS trick: the handler address minus 1 is pushed onto the stack (hi first, then lo), then RTS is executed. The 6502 retrieves the address, increments it by 1 and jumps to the handler. This avoids a JMP table and saves a few bytes.

Example: command 'G' (5th character in $4F9D) → ATAMON reads the 2 bytes at $4FC8 + (index × 2), pushes them in reverse order, and does RTS to the handler.

Built-in Disassembler Tables ($4FF9+)

ATAMON has its own mini-disassembler (command D). It uses two internal tables:

1. 6502 Mnemonics: 3-letter encoded entries (56 official mnemonics)

2. Addressing modes: table of operand sizes and formats for each opcode

These tables cover only the official opcodes of the 6502. Illegal opcodes are not recognised by ATAMON's disassembler and would be displayed incorrectly.

→ See Annex B at the end of this document for the complete list of the 56 recognised mnemonics.

Note: in the ATAMON binary, addresses $4F43–$52B1 contain data (text strings, character tables, vectors). A linear disassembler interprets these bytes as instructions — many of which fall into the category of undocumented 6502 opcodes ($02 *KIL, $03 *SLO, $3A *NOP, etc.). These are false positives due to the nature of the data, not intentional use of illegal opcodes in ATAMON's code.

11. How to Use ATAMON

Starting Up

From Atari DOS, select L. BINARY LOAD then type D:ATAMON. ATAMON displays its banner (*C + registers) and the Atari cursor waits for your first command.

Special Keys

Note: ATAMON relies on CIO (screen editor E:) to read commands. The standard Atari editor functions (cursor movement, deletion) are available before validating with RETURN.

Typical Startup Display

xxxxxxxxxx
*** ATAMON V1.3 - (c) 1983 by ATARI  ***
*C
  PC  SP AC XR YR NV\BDIZC
; 4000 FD 00 00 00 00110000

Sample Session

xxxxxxxxxx
; Display memory from $4000
M 4000

; Modify 8 bytes at $6000 (free zone)
: 6000 A9 FF 8D 00 D0 4C 00 60

; Disassemble from $4000
D 4000

; Run program at $4000
G 4000

; Copy $4000-$40FF to $6000, then verify
T 4000,40FF,6000
V 4000,40FF,6000

; Fill $6000-$60FF with NOPs ($EA) — free zone, outside ATAMON
F 6000,60FF,EA

; Read disk sector 1 into buffer ($0680)
E 0001

; Rewrite buffer to sector 1
W 0001

; Calculate $4000 + $0100
* + 4000,0100

; Quit to DOS
X

12. Historical Notes

ATAMON (abbreviation for ATAri MONitor) is a machine language monitor marketed by ATARI in 1983 in Germany, the same year as the launch of the Atari 800XL.

The DXG 5724 disk also contains:

• DOS.SYS: the Atari DOS 2.x disk operating system (39 sectors)

• DUP.SYS: the disk management utility (42 sectors)

These three programs make up a complete disk: DOS + utilities + debugging monitor.

Analysis of the disk revealed no particular copy protection. Analysis of all 720 sectors confirmed the absence of phantom sectors (phantom_count = 0 for all sectors), intentional bad CRCs, or any other copy protection mechanism. The original ATAMON disk was not copy-protected.

13. Technical Notes on Disassembly

Known 6502 Illegal Opcodes

JMP Indirect Bug

The 6502 has a hardware bug: JMP (addr) incorrectly reads the high byte if addr ends in $FF. Example: JMP ($10FF) reads $10FF (lo) and $1000 (hi) instead of $1100. In ATAMON, the two JMP (ind) present ($47BF JMP (DOSVEC) and $47E4 JMP ($4F41)) do not have addresses ending in $FF — no bug in this program. Note: JMP ($4F41) is the execution jump to the saved address (PCL at $4F41, PCH at $4F42).

Annex A — Zero Page Glossary ($00–$FF)

The zero page is the first 256-byte block of RAM ($00 to $FF). On the 6502, it is special for two reasons:

• Instructions that access it only use one address byte instead of two → they are shorter and faster.

• The 6502 can use it as an area of "extra registers": 16-bit pointers, counters, temporary variables.

The Atari OS and ATAMON use it extensively. Here are the most important locations, explained for a beginner:

Atari OS Variables (Reserved by the System)

Variables Used by ATAMON

These addresses are reserved by ATAMON while it is loaded. Modifying them with : or , may disrupt the monitor's operation.

Tip: use M 0000 00FF to display the entire zero page and observe how these values change with different operations.

Unofficial documentation reconstructed from binary XEX analysis and 6502 disassembly. References: De Re Atari (APX 90009), Atari 8-bit FAQ, Altirra 4.40 source, AtariWiki — 6502 Assembly Code, Unused Opcodes, OS ROM listing, Mapping the Atari, Atari Custom Display Lists (Atarimania), Display Lists Simplified (Atari magazines), ANTIC registers (xmission.com/~trevin).

Annex B — The 56 Official 6502 Mnemonics

ATAMON's built-in disassembler (command D) recognises exactly these 56 instructions.

Load / Store

Register Transfers

Stack

Arithmetic

Increment / Decrement

Logical Operations

Shifts and Rotations

Comparisons

Conditional Branches

All branches are relative (signed offset of −128 to +127 bytes from the next instruction).

Jumps and Calls

Software Interrupt

Flag Operations

Miscellaneous

Annex C — Illegal / Undocumented 6502 Opcodes

These opcodes do not exist in the official MOS Technology 6502 specification. They result from unintended combinations of the processor's internal logic. Their behaviour is reproduced by the ATAMON disassembler (command D), which displays them preceded by a *.

Warning: most are unstable depending on the processor revision or supply voltage. Avoid in production code; useful for analysing old programs that exploit them.

Fatal Instructions

Combined Read-Modify-Write Instructions

These opcodes perform two operations in one: a modification in memory (or on the accumulator) then a logical/arithmetic operation with A.

Combined Load / Store

Accumulator Instructions

Unstable Memory Instructions (depend on addr_hi)

Illegal NOPs (multi-byte, no effect)

These opcodes behave like NOP (do nothing visible) but consume 2 or 3 bytes — the CPU reads and ignores them.

Annex D — Known Atari Labels

Symbolic addresses recognised by the ATAMON disassembler (command D). They appear in the disassembly in place of the raw hexadecimal address.

Zero Page — OS Variables ($00–$FF)

Page 2 — Interrupt Vectors ($0200–$02FF)

Page 3 — SIO DCB ($0300–$035F)

Hardware Registers — GTIA ($D000)

Hardware Registers — POKEY ($D200)

Hardware Registers — PIA ($D300)

Hardware Registers — ANTIC ($D400)

OS ROM Entry Points ($E4xx)

Math ROM ($D8xx)

Annex E — Atari 800XL Hardware Registers — Quick Reference

Summary of hardware registers for the four custom chips of the Atari 800XL, with their typical usage in programming.

GTIA — Graphic Television Interface Adaptor ($D000–$D01F)

POKEY — Potentiometer and Keyboard ($D200–$D20F)

PIA — Peripheral Interface Adaptor ($D300–$D303)

ANTIC — Alphanumeric Television Interface Circuit ($D400–$D40F)

Fixing the C Command Bug (Patch)

The Bug

The C command in ATAMON V1.3 has been broken since its publication in 1983. Regardless of the syntax used, it always returns ? and writes nothing to memory.

Cause: In ATAMON's code, every command that takes multiple arguments must, between each argument, call routine $43AE (SEPARATOR_CHECK). This routine reads and consumes the comma , that separates arguments in the command line.

The C command handler (at address $4BE9) correctly reads the destination address via JSR $4256, but then calls directly JSR $4280 (READ_BIN, which reads 8 bits) without going through $43AE. Result: READ_BIN reads the comma , (code $2C) instead of the first binary digit 0 or 1. The comma is written to memory ($2C = 44), then the program encounters an error and displays ?.

All other multi-argument commands (F, T, V, L, H, I...) correctly call $43AE between their arguments. C is the only one that omits it.

The Fix

The fix consists of adding the missing call to $43AE without modifying the existing code. Since ATAMON fully occupies the $4000–$52B1 range, a small intermediate program ("trampoline") is installed in the first free byte after the code: $52B2.

Step 1 — Redirect the READ_BIN call

At address $4BF6, replace:

xxxxxxxxxx
20 80 42   JSR $4280   ; READ_BIN (direct call — bug)

with:

xxxxxxxxxx
20 B2 52   JSR $52B2   ; -> trampoline