Commodore 64 Programmer's Reference Guide

The Commodore 64 User’s Guide that came in the box taught you to type PRINT. Everything else (where the screen lived in memory, how to make the SID chip sing, what the 6510 processor’s own I/O port did) was in a second book you had to buy. Compute!’s Gazette warned readers in 1983 that its $19.95 price “may seem a bit expensive, but it is well worth the price”. For the rest of the decade the Commodore 64 Programmer’s Reference Guide was the book other writers cited by page number. When magazines told readers where to look something up, the answer was usually “page 376 of the C-64 Programmer’s Reference Guide” or “Chapter 5 of the Commodore 64 Programmer’s Reference Guide”.

Fast facts

Publisher: Commodore Business Machines, Wayne, Pennsylvania; distributed by Howard W. Sams & Co., Indianapolis.
Copyright: 1982. The copy described here is the first edition’s third printing, of 1983.
Price: $19.95 in the US, sold separately from the computer. British mail-order adverts of 1986 and 1987 gave its price as £12.95 and £9.95. ISBN 0-672-22056-3.
Length: 486 numbered pages of text and index, then a quick-reference card and a fold-out schematic of the C64.
Structure: six chapters and 16 appendices, lettered A to P.

Who it was for

The introduction set its limits plainly. The guide was “not designed to teach the BASIC programming language or the 6502 machine language”; beginners were sent back to the User’s Guide “that came with your computer”. It promised instead the information you need “from the simplest example all the way to the most complex”, and it was not shy about the hardware: the C64’s sprites and character graphics were “the most detailed and advanced animated pictures in the microcomputer industry”, and the SID was “the best built-in synthesizer available in any personal computer”.

Reviewers agreed that it delivered. Commander, a Commodore monthly from Tacoma, Washington, wrote in early 1983 that the book was “much more than the name implies”, with “a large amount of technical data on the primary chips” and the schematic folded into the back. It singled out a table of screen and character colour combinations that blurred on a colour television, and the KERNAL jump table. Its index was “very useful for quick reference”, though the reviewer noticed that NMI was missing from it. “If you plan on doing more than minimal Basic/machine language programming,” Commander concluded, “the guide will be a necessity and a good investment.”

What is inside

The six chapters follow the order of the machine.

BASIC programming rules. Numbers, variables, operators and the order they are worked out in, and how to “crunch” a program to save memory.
BASIC language vocabulary. Every keyword in Commodore BASIC V2, alphabetically, with example programs, then the keyboard and screen editor.
Graphics. Video banks, screen, colour and character memory, programmable characters, multicolour and bitmap modes, smooth scrolling, sprites, collision detection and the raster register. A worked example, “The Dancing Mouse”, animates a sprite by switching its data pointer between three shapes.
Sound and music. The SID’s voices, waveforms, envelope generator, filter, synchronisation and ring modulation.
BASIC to machine language. A beginner’s introduction to the 6510, the full instruction set with timings, memory management, the KERNAL and its callable routines, and a complete memory map.
Input/output guide. Printer, modem, cassette and disk, the game ports with joysticks, paddles and light pen, the RS-232 interface, the user port, the serial bus, the expansion port and the Z80 CP/M cartridge.

The appendices are where programmers lived. Appendix E lists the SID register values for eight octaves of notes. Appendix G maps the VIC chip’s registers. Appendices L to O reprint the manufacturers’ data sheets for the 6510, the 6526 CIA, the 6566/6567 VIC-II and the 6581 SID, with pinouts, register maps, electrical ratings and timing descriptions written for hardware engineers.

Hints of what was possible

In places the guide pointed past BASIC. Because the VIC-II maintained the sprites itself, it said, “it is even possible to write a good quality game in BASIC!” Two pages on interrupts went further. “This powerful interrupt structure lets you use split screen modes. For instance you can have half of the screen bit mapped, half text, more than 8 sprites at a time, etc. The secret is to use interrupts properly.” Then it added that “BASIC isn’t fast enough to do this very well”, so anyone who wanted raster interrupts should work in machine language. The VIC-II data sheet in Appendix N describes the cost of the chip’s memory fetches too: on every eighth raster line of the display it stops the processor for 40 cycles to fetch the next row of character pointers.

Mistakes and gaps

Readers found errors. In Ahoy! in October 1984, Dale Rupert showed that joystick port 1 is read at location 56321 and port 2 at 56320. The guide’s joystick routine reads 56320 and says “For the second joystick” to use 56321, so, Rupert wrote, “From the Programmer’s Reference Guide, I would have thought that Port 1 data is stored at 56320 and Port 2 data is at 56321, but that is obviously incorrect.” In 1987 Cyndie Merten, a former Commodore programmer, listed in RUN some “obscurities” she had found while writing the Plus/4’s reference guide: the entry for NOT describes a “twos-complement” result, when the operator inverts each bit, which gives the ones’ complement.

The instruction set covers the 6510’s documented 56 instructions and nothing else. The undocumented opcodes that later demo and game programmers used do not appear.

Sources

Commodore Business Machines, Commodore 64 Programmer’s Reference Guide (first edition, third printing, 1983; copyright 1982): copyright page (p. ii); contents (pp. iii–vii); introduction, “What’s Included?” (pp. ix–x); NOT (p. 63); sprites and “a good quality game in BASIC” (p. 131); colour combinations (p. 152); interrupts, split screens and “BASIC isn’t fast enough” (pp. 151–152); “The Dancing Mouse” (pp. 166–172); the game ports and joystick routine (pp. 343–344); Appendix E, music note values (pp. 384–387); Appendix L, 6510 features, “56 Instructions”; Appendix N, VIC-II system interface (pp. 447–448); back cover (Howard W. Sams, $19.95, ISBN).
Commander, March/April 1983, p. 55: review ($19.95, 486 pages, the chip data, fold-out schematic, colour table on p. 152, the KERNAL jump table, the index without NMI, “a necessity and a good investment”).
Larry Isaacs, “64 Explorer”, Compute!’s Gazette issue 2, August 1983, pp. 95–96: review ($19.95 from Howard W. Sams, “well worth the price”, six chapters and 16 appendices, 487 pages).
Ahoy! issue 17, May 1985 (“page 376 of the C-64 Programmer’s Reference Guide”), and issue 26, February 1986 (“Chapter 5 of the Commodore 64 Programmer’s Reference Guide”): examples of the guide cited as the place to look.
Dale Rupert, “Rupert Report”, Ahoy! issue 10, October 1984, pp. 19–20: the joystick port addresses.
Cyndie Merten, “C-64 reference guide clarifications”, RUN Special Issue, 1987: the NOT operator.
Commodore Computing International, vol. 4 no. 7, February 1986: readers’ club offer of the guide at £9.95, against a listed price of £12.95. Commodore User, April 1987: mail-order advertisement, “Pub. price £9.95”.