The MAC/65 ToolKit

Year
1984
Publisher
Optimized Systems Software, Inc. (OSS)
Type
Development tool
Category
Macro library for the MAC/65 assembler
Developer
Stephen D. Lawrow
Language
MAC/65 assembly source
Requirements
48K Atari 400/800/XL/XE; MAC/65 (cartridge or disk version); a DOS disk to boot (the ToolKit disk has no DOS on it)
Yellow OSS package for The MAC/65 ToolKit, with the words Precision Software Tools repeated in the background and the line An Essential Aid for ALL MAC/65 Programmers

Overview

The MAC/65 ToolKit is a disk of macro libraries for OSS's MAC/65 assembler. It was published by Optimized Systems Software in 1984 and credited to Stephen D. Lawrow, the author of MAC/65 itself. Instead of writing the same CIO calls, multiply routines and player-missile setup code for every project, you .INCLUDE the ToolKit files and call macros whose names and parameters copy Atari BASIC: OPEN, PRINT, GR, PLOT, DRAWTO, SOUND, POKE, even TRAP.

OSS sold it to both ends of the market. Its manual says the BASIC-like syntax makes it easier for beginners to move to machine language, and that professionals save time because the run-time code for common jobs is already written and debugged.

What is on the disk

The disk holds three MAC/65 source libraries:

  • KERNEL.M65 is the core. It provides two-byte operations, integer maths, IF-style tests, DO loops, error trapping, I/O (including multi-byte transfers and binary loading), graphics, sound and random numbers. The other two libraries need it.
  • PMGR.M65 handles player-missile graphics. It sets up single-line-resolution players at a PMBASE page you choose, moves players and missiles from a vertical-blank routine, sets their colour, width and height, swaps shape data, and tests for player, missile and playfield collisions.
  • SCROLL.M65 gives automatic fine scrolling. One macro, SCRDIM, sets the ANTIC mode (2 to 7), the size of the whole display in characters, the screen address and where to build the display list. It then installs a deferred vertical-blank routine. After that you steer the scroll by poking a location with the same direction numbers that BASIC's STICK(0) returns, so a joystick value can be passed straight through. The manual points readers to De Re Atari and to ANALOG's fine-scrolling series (from October 1983) for the theory behind it.

How it works

You put the .INCLUDE lines at the very start of your source, for example .INCLUDE #D:PMGR.M65, and then write macro calls. A few rules run through the whole library:

  • Every macro preserves the X and Y registers. The accumulator and flags are generally undefined afterwards.
  • All of the ToolKit's global labels start with QQ, so you should not start your own labels that way. The exceptions are the scroll control locations and the loop counters I, J and K.
  • A numeric parameter below 256 is treated as an immediate value; anything else is taken as a memory address. POKE $2000,5 therefore becomes LDA #5, while POKE $2000,300 loads from location 300. The manual warns that this makes zero-page labels and forward references unsafe as macro parameters, although the branching macros handle forward labels.

The integer maths macros chain through the floating-point register FR0. The manual's own example computes (25×30)/10+200−50:

3010  CALC 25
3020  MUL 30
3030  DIV 10
3040  PLUS 200
3050  MINUS 50
3060  STORE RESULT

Loops look much like BASIC too. DOI START,END ... LOOPI counts the two-byte variable I with a step of 1, and DOJ and DOK nest inside it. TRAP sets an error address. By default it points to a ToolKit routine that prints the error number and does a system reset. The ToolKit adds two error codes of its own: 175, when PRINUM cannot fit a number in its field, and 176, when BLOAD is given a file that is not in binary load format.

Using it today

ToolKit disk images circulate with the other OSS material. The files are ordinary MAC/65 sources, so the easiest way to use them is in MAC/65 under emulation: boot DOS with the cartridge (or the disk version), then swap in the ToolKit disk. People who assemble on a PC with a cross-assembler such as ATasm have asked how to get the macros out as text. The usual route is to mount the ATR, load each .M65 file into MAC/65 and LIST it to a text file. Expect to adapt a few MAC/65-specific details by hand. Even if you never assemble with them, the PMGR and SCROLL listings are compact, readable examples of vertical-blank-driven player movement and fine scrolling.

Credits