BUG/65

Year
1982
Publisher
Optimized Systems Software, Inc. (OSS)
Type
Development tool
Category
Disk-based 6502 debugger and monitor
Developer
McStuff Company (as McBug)
Language
6502 machine language
Requirements
Atari 400/800 or XL/XE with 48K and a disk drive; OS/A+ or DOS XL (loads as an extrinsic .COM command); best used alongside MAC/65
Typewritten title page reading: a reference manual for BUG/65, an assembly language debugging program for use with 6502-based computers built by Apple Computer, Inc., and Atari, Inc., copyright 1982 by McStuff Company and Optimized Systems Software

Overview

BUG/65 is the machine-language debugger from Optimized Systems Software, the company behind OS/A+, DOS XL and MAC/65. It is a disk-based program, not a cartridge. It loads as BUG65.COM, an extrinsic command under OS/A+ or DOS XL, so you type BUG65 at the D1: prompt and it relocates itself to the bottom of free memory.

It was not written at OSS. The manual says it was developed by the McStuff Company under the name "McBug", and the title page describes it as a debugger for 6502 machines from both Apple and Atari. The software and manual are dated 1982. OSS later bundled it with DOS XL: the December 1983 DOS XL 2.30 manual has "Now Includes BUG/65" on its cover, and a 1985 Antic survey of disk operating systems mentioned that OSS had started packing BUG/65 in with DOS XL.

The preface describes a tool for experienced assembly programmers that deliberately trades memory for features. It takes 8K of code and data and needs a 48K machine.

Features

The command set is a single letter per command, and several commands can be typed on one 100-character line:

Command Purpose
D / S / A Display memory; change it in hex (S) or as ASCII text (A)
F, M, C, L Fill, move, compare and search memory blocks
G Go, with an optional breakpoint, register presets and a pass count
T Trace one or more instructions; TS treats a whole subroutine as one step
U Call a user subroutine, passing a 16-bit parameter in X and Y
V / X View the user registers / change one
Y Disassemble a block of memory
Z Instant assembler, with simple labels L0–L9 and / (origin) and + (byte) pseudo-ops
R / W Read or write a binary load file (W can append)
R% / W% Read or write raw disk sectors
H, K Hex arithmetic; hex to decimal conversion
I, P, Q Directory listing, output to screen and/or printer, quit to DOS
E / J Execute or create a command file of BUG/65 commands

Pressing RETURN on an empty line repeats the last command line, and a trailing / repeats a line forever, for example to watch memory change. B sets a relocation base, so you can give addresses relative to the start of a module from a relocating assembler.

How it works

Two design choices set BUG/65 apart from simpler monitors:

  • Self-protection. Any command that would overwrite BUG/65's own 8K, such as moving a block on top of it, fails with a PROTECTION ERROR. A byte in the configuration table can switch this off.
  • Page-zero sharing. BUG/65 needs some zero-page locations, so it keeps two copies of them, its own and the user's, and swaps them when you Go to your program or break back. Commands that refer to those addresses are quietly redirected to the user's copy. You can fill $80–$FF with zeros and then display zeros without crashing the debugger. The manual admits that this translation makes some commands, such as large fills, noticeably slow.

As shipped, the program carries a relocation bitmap. BUG65 8000 loads it at $8000 instead of LOMEM, and the restart entry point is always $200 above the load address. You can then save a fixed-address copy from DOS. The manual's example is SAVE BUG7000.COM 7200 9000. Near the start of the code is a configuration table with patchable vectors for the screen and printer output routines. At load point + $220 is a User Command Interface: any character that is not a BUG/65 command is passed to a USRCMD vector, so you can add your own commands.

Versions

The copy bound into the DOS XL 2.30 manual is labelled Rev 1.1, but an insert says the software is version 2.0. The insert lists the changes: new commands to switch memory protection off and on, separate single- and double-density forms of the sector read/write commands, and native support for OS/A+ version 4, which no longer needs a patch.

Using it today

BUG/65 still runs under emulation, but modern users report a few quirks. On one AtariAge user's DOS XL disk it crashed when started without an address, yet ran correctly with an explicit load point such as BUG65 2000 (anything up to about $8000 worked). Under SpartaDOS 3.2g it returns to the root directory, and it cannot read object files with full 8.3 names on another drive or in a subdirectory. Its printer output (P) does not work with the XL/XE operating system. A small community patch reroutes the print routine through an IOCB to fix this.

Many programmers prefer OSS's DDT debugger, which came bundled with MAC/65 and also exists as a disk-based "Extended DDT", or the debugger built into the Altirra emulator. BUG/65 is still handy for poking at small pieces of code from the command line and for quick memory dumps on real hardware.

Credits