Apple ][+ machine language

“Apple ][+ machine language” is the name for 6502 machine code as it was written on Apple’s second personal computer. The processor’s instruction set is the same as on any other 6502 (see 6502 Assembler). What made Apple II programming different was everything around the CPU. Programmers typed hex bytes into a Monitor built into ROM, called firmware routines at fixed addresses, and controlled graphics, sound and the keyboard by reading or writing memory locations. On the Apple II Plus, which sold from June 1979 to December 1982, machine language was the only way to get full speed from the hardware. Many landmark programs of the period were written in it, including Apple DOS, VisiCalc and many of the best-known games.

This encyclopedia dates the entry to 1977, the year the original Apple II shipped with its machine-language Monitor. The “][+” in the name refers to the II Plus of 1979. Its Autostart ROM kept the same Monitor entry points, so machine-language programs written for the original Apple II generally ran on the Plus. The main exceptions were programs that relied on Integer BASIC ROM routines.

History & Origins

Wozniak’s Monitor (1977)

The Apple II did not boot into BASIC. It powered up into a machine-code monitor, and BASIC had to be started by pressing Ctrl-B and Return. The Integer BASIC ROMs contained a monitor, a “mini-assembler” and a disassembler for creating and debugging assembly language programs. According to accounts of the machine’s development, Wozniak hand-assembled the monitor as the Apple II’s first program, before writing Integer BASIC.

Apple began shipping complete Apple II systems on 10 June 1977. The earliest machines came with a photocopied mini-manual. In early 1978 Apple replaced it with the Apple II Reference Manual, known from its cover as the Red Book. The Red Book included an assembly language source listing of the Monitor ROM. That meant every Apple II owner could read, line by line, how the firmware worked, and use its routines in their own programs.

Wozniak also put SWEET16 into the Integer BASIC ROM. It is a byte-code interpreter for an imaginary 16-bit processor, built because he needed to manipulate 16-bit pointers on an 8-bit machine. He described it in BYTE in November 1977 as “The 6502 Dream Machine.” Machine-language programmers could switch into SWEET16 in the middle of a routine for compact pointer arithmetic, then return to native 6502 code.

The Autostart ROM and the Apple II Plus (1978–1979)

In November 1978 John Arkley at Apple revised the original Monitor to create the Autostart ROM. On power-up it searched for a disk controller card and, if it found one, booted the disk. If not, it jumped into BASIC instead of leaving the user at the Monitor prompt. RESET now went through “soft-entry” vectors on memory page $03, so a runaway program could be stopped without losing what was in memory. A new ESC editing mode used the I, J, K and M keys to move the cursor.

The Apple II Plus shipped with this ROM in June 1979 for $1,195, with Microsoft-derived Applesoft BASIC replacing Integer BASIC. The change came at a cost to assembly programmers. With Applesoft taking up the ROM space, the II Plus lost Integer BASIC, the mini-assembler and SWEET16, and the Monitor lost its STEP and TRACE commands and a set of 16-bit multiply and divide routines. Some writers at the user-group magazine reportedly Call-A.P.P.L.E. nicknamed the new machine the “Apple II Minus.” The missing routines could be restored by loading Integer BASIC into a Language Card or installing a firmware card.

When Apple prepared a new Reference Manual for the II Plus, it reportedly found that the Monitor source files had been destroyed. A backup at the time-sharing service Call Computer had been run with the source and destination disks swapped. Arkley rebuilt the original Monitor source from the Red Book listing, then disassembled his own changes to recreate the Autostart source. Those rebuilt listings were printed in the 1981 edition of the Apple II Reference Manual.

Design Philosophy

Apple II machine language was shaped by Wozniak’s hardware design, which used as few chips as possible and did many tasks in software:

• Firmware as a library. The Monitor’s subroutines sat at fixed addresses and were documented in the Reference Manual. Programs called COUT to print a character or RDKEY to read a key, instead of driving the hardware directly. Later ROM revisions kept these addresses so that existing software still worked.
• Hardware as memory. Page $C0 (addresses $C000–$C0FF) is I/O space. Reading $C000 returns the last key pressed. Touching $C030 clicks the speaker. Accessing $C050–$C057 flips the video “soft switches” between text, low-resolution and high-resolution graphics.
• Vectors in RAM. Output, input, RESET and the Ctrl-Y command all go through jump vectors in low memory (pages $00 and $03). A program can patch these vectors to redirect output, intercept keystrokes or add Monitor commands. DOS used this technique to hook itself into the system.
• No separation between user and system. The 6502 has no memory protection. A machine-language program owns the entire machine, which gave programmers full control and made crashes a routine part of development.

Key Features

The Monitor

From Applesoft BASIC, CALL -151 jumps to the Monitor, which shows an asterisk prompt. (-151 is the signed form of address $FF69.) Everything is typed in hexadecimal:

On machines with the Integer BASIC ROMs (the original Apple II, or a II Plus with a Language Card or firmware card running Integer BASIC), F666G starts the mini-assembler. At its ! prompt, users typed mnemonics one line at a time and got the object code back immediately. It had no labels, symbols or macros; branch targets and data addresses were given as hex numbers.

A Program Typed in Hex

The listing below prints HELLO by calling the Monitor’s character-output routine COUT at $FDED. The Apple II uses ASCII with the high bit set for normal text, so H is $C8 rather than $48, and carriage return is $8D:

1
2
3
4
5
6
7
8

0300- A2 00       LDX #$00        ; X indexes the string
0302- BD 0E 03    LDA $030E,X     ; fetch next character
0305- F0 06       BEQ $030D       ; zero byte ends the string
0307- 20 ED FD    JSR $FDED       ; COUT: print character in A
030A- E8          INX
030B- D0 F5       BNE $0302       ; always taken for short strings
030D- 60          RTS             ; back to the Monitor or BASIC
030E- C8 C5 CC CC CF 8D 00        ; "HELLO", CR, terminator

On an Apple II Plus, the programmer entered it at the Monitor prompt and ran it:

1
2
3

*300: A2 00 BD 0E 03 F0 06 20 ED FD E8 D0 F5 60 C8 C5 CC CC CF 8D 00
*300G
HELLO

From Applesoft, the same routine is CALL 768. BASIC programs often carried short machine-language routines in DATA statements and POKEd them into page 3, a free area of memory, before calling them. With DOS loaded, routines were saved to disk as binary files with BSAVE and loaded and run with BLOAD and BRUN.

Commonly Used Addresses

Sound shows how bare the hardware was. The speaker has no tone generator, so a program produces a note by touching $C030 in a timed loop, and the pitch depends on the loop’s cycle count.

Tools and Literature

Once a disk drive and more memory were common, most programmers moved from typing hex to full editor-assemblers with labels, macros and source files on disk:

• Merlin by mathematician Glen Bredon, a macro assembler whose manual is dated 1982. It included the Sourceror disassembler. Its documentation described it as following the conventions of the earlier TED ][+ editor-assembler. After Bredon’s death his widow reportedly released his Apple II software and source code into the public domain in August 2000.
• Cross-development on larger machines. Paul Laughton wrote DOS 3.1 using punched cards and a minicomputer. Bricklin and Frankston built VisiCalc with an assembler on a time-sharing system and then a Prime minicomputer.
• Books and magazines. Randy Hyde’s Using 6502 Assembly Language (Datamost), written for Apple II programmers, came out in 1981. Roger Wagner’s Assembly Lines ran in Softalk from October 1980 to June 1983, and its first fifteen columns were collected as Assembly Lines: The Book in 1982. Magazines such as Call-A.P.P.L.E. and Nibble published type-in machine-language listings for readers to enter at the Monitor.

Evolution

The II Plus was replaced by the Apple IIe in January 1983. The IIe kept the Monitor entry points and soft switches while adding 80-column support and more memory. The enhanced IIe and the Apple IIc moved to the 65C02 and restored a mini-assembler to the Monitor. The Apple IIGS used the 16-bit 65C816, which starts in a 6502-compatible emulation mode, so most well-behaved II Plus machine-language software could still run. Apple DOS 3.3 (1980) was followed by ProDOS in 1983, which added a documented machine-language interface (the MLI) in place of DOS 3.3’s undocumented internals. Programmers had previously learned those internals from books such as Worth and Lechner’s Beneath Apple DOS (1981).

Current Relevance

The Apple II Plus has been out of production since 1982, so this encyclopedia lists its machine language as Historical. It is still widely studied and written:

• Emulators such as AppleWin and MAME emulate the II Plus, its ROMs and its disk drives, so the Monitor session above can be reproduced on a modern computer.
• Modern cross-assemblers. Brutal Deluxe’s Merlin 32 (January 2015) brings Merlin syntax to modern systems, and general 6502 tools such as ca65 are widely used for Apple II targets.
• Preserved source code. DOS 3.1 (Computer History Museum, 2013) and Prince of Persia (GitHub, 2012) can now be read as primary sources. Assembly Lines: The Complete Book, which collects all 33 of Wagner’s columns, was published in 2014 and is freely available as a PDF.
• Retro development. Hobbyists still write new Apple II games and demos in 6502 machine language. The Assembly Lines name continues in an Apple II retrocomputing podcast.

Why It Matters

For many people in the late 1970s and early 1980s, the Apple II Monitor was their first close look at how a computer works. Because the Red Book printed the firmware source, users could study the ROM and then call its routines, patch its vectors and bypass it when they needed speed. That openness helped build a large commercial software industry on the Apple II. VisiCalc, reportedly the reason many businesses bought their first Apple II, was written in this language, as were its operating system and many of the games that made the platform successful.

The II Plus version of the language also shows the trade-offs of fitting firmware into a few kilobytes of ROM. Adding a floating-point BASIC in 1979 meant removing the mini-assembler, SWEET16 and the Monitor’s single-step debugger, a loss that assembly programmers noticed. The practice of documenting fixed firmware entry points and memory-mapped hardware, and keeping them stable across models, is why software written for the 1977 Apple II could run on later Apple II models into the IIGS era.