6502-PRG

A 6502 assembly language program template for the A.C. Wright 6502 family of computer systems.

📖 Guide:AC6502 Documentation — the user's and programmer's guide for the whole family. This template is walked through end to end in Starting from a template.

Overview

Programs for this system are loaded into RAM at $0800 and executed from BASIC. Unlike cartridges (which replace ROM), programs run entirely in RAM alongside the BIOS, Kernal, BASIC interpreter, and Monitor — all of which remain available.

How It Works

1. The program is loaded into RAM at $0800 — normally with BASIC's LOAD, from CompactFlash or over serial
2. BASIC's RUN command executes the tokenized stub at the start of the file
3. The stub decodes to 10 SYS 2060, which calls the machine code entry point at $080C
4. Your program runs with full access to the Kernal jump table
5. Return to BASIC with RTS

Memory Layout

Range	Contents
$0000–$0039	Zero page — system pointers, Monitor and XModem scratch (see 6502.inc for details)
$003A–$00FF	Zero page — free for user programs (198 bytes)
$0100–$01FF	CPU stack
$0200–$02FF	Input ring buffer (managed by Kernal)
$0300–$03FF	Kernal variables (vectors, cursor, HW flags, etc.)
$0400–$05FF	User/BASIC variables
$0600–$07FF	CompactFlash sector buffer — clobbered by any filesystem call
$0800–$080B	BASIC startup stub (10 SYS 2060)
$080C–$7FFF	Your program code and data (~30 KB available)
$8000–$9FFF	I/O hardware registers
$A000–$A0FF	Kernal jump table (stable API)

BASIC Startup Stub

The first 12 bytes of every program file contain a tokenized BASIC line that serves as a loader:

Address	Byte	Meaning
$0800	$0A	Next-line pointer lo → $080A
$0801	$08	Next-line pointer hi
$0802	$0A	Line number 10 (lo)
$0803	$00	Line number 10 (hi)
$0804	$A5	TOK_SYS
$0805	$32	'2'
$0806	$30	'0'
$0807	$36	'6'
$0808	$30	'0'
$0809	$00	Line terminator
$080A	$00	End-of-program sentinel (lo)
$080B	$00	End-of-program sentinel (hi)
$080C	…	Machine code entry point (2060 decimal = $080C)

Kernal Services

The system is already fully initialized when your program runs. Key entry points:

Address	Routine	Description
$A000	Chrout	Output character (routed by IO_MODE)
$A003	Chrin	Read character from input buffer (non-blocking — C=1 with the character in A, C=0 if none; loop for blocking behaviour)
$A00C	BufferSize	Number of unread bytes in input buffer
$A018	VideoClear	Clear screen and reset cursor
$A01B	VideoPutChar	Write character at cursor position
$A01E	VideoSetCursor	Set cursor position (X=col, Y=row)
$A027	VideoSetColor	Set text color (A = fg<<4 | bg)
$A033	SidPlayNote	Play note (A=voice, X=freqLo, Y=freqHi)
$A075	SysDelay	Delay A=lo, X=hi centiseconds
$A048	ReadJoystick1	Read joystick 1 bitmask

See 6502.inc for the complete jump table with calling conventions.

Hardware Detection

Check HW_PRESENT ($030D) before using optional hardware:

lda HW_PRESENTand #HW_SID ; Is SID present?beq @NoSound ; Skip sound code if notjsr SidPlayNote@NoSound:

Building

Prerequisites

CC65 Compiler

On macOS, install via Homebrew:

brew install cc65

For other platforms, see the cc65 project.

bin2woz (optional — for Wozmon loading)

npm install -g bin2woz

Converts the binary to a format loadable via the Wozmon serial monitor. See the bin2woz project.

cffs (optional — for CompactFlash images)

npm install -g cffs-image-tool

Creates CompactFlash disk images with the program file. See the cffs project.

6502 CLI (optional — for make run)

Installed via the 6502-EMULATOR app's Settings → Command Line → Install.

Build Commands

Command	Description
make	Build all targets (.prg, .woz, and CF image)
make build	Assemble only (Program.prg)
make view	Display hexdump of the built program
make woz	Create Wozmon-compatible file (Program.woz)
make cf	Create CompactFlash disk image with the program
make run	Launch the emulator app with the built program loaded
make clean	Remove build artifacts

Build Output

make

Produces:

• Program.prg — Raw binary, load address $0800
• Program.woz — Wozmon-compatible format for serial upload
• Program.lst — Assembly listing file for debugging
• Program.img — CompactFlash disk image with the program

Loading & Running

Use BASIC's LOAD. Requires BIOS v1.3 or later.

From CompactFlash — the usual case:

LOAD "PROGRAM.PRG"
RUN

Over serial, with no CF card:

LOAD

Then send Program.prg from the host with any terminal that speaks XMODEM (128-byte blocks, checksum mode). The transfer is padded up to a block boundary, which is harmless.

Either way, RUN executes the stub and SYS 2060 enters your code at $080C.

From the Monitor, if you are already there:

L "PROGRAM.PRG"
X

L loads to $0800 by default and X returns to BASIC, where RUN works as usual.

Why the loader matters

Your machine code lives past the end-of-program marker at $080A, where BASIC would otherwise put its variables. Keeping the two apart depends on the loader telling BASIC how many bytes it wrote, so BASIC can place VARTAB past the whole image rather than at the end of the tokenized line chain.

LOAD and the Monitor's L both do this as of BIOS v1.3. Wozmon does not — it writes bytes one at a time with no notion of a length, so BASIC falls back to walking the line chain, VARTAB lands at $080C on top of your code, and the first variable assignment destroys it. Use Wozmon for code you will enter from the Monitor, not for programs you intend to RUN.

On BIOS versions before v1.3 the byte count was discarded on every path, so all three loaders had this problem.

Template Structure

File	Purpose
Program.asm	Main source — BASIC stub, entry point, example code
6502.inc	System include file — Kernal jump table, hardware registers, constants
6502.cfg	Linker configuration — memory layout for RAM programs
Makefile	Build system

Customizing

1. Edit Program.asm — replace the example code after the Start: label with your program
2. Do not modify the BasicStartup bytes — they must remain at $0800 for BASIC RUN to work
3. Return to BASIC with RTS when your program finishes
4. Add additional .asm files and .include them as needed
5. You have ~30 KB of RAM ($080C–$7FFF) for code and data

Related

• 6502-ACE — the hardware, and the index of the whole family
• 6502-BIOS — the firmware behind the Kernal jump table; 6502.inc here tracks its published API
• 6502-EMULATOR — run a program without hardware (make run)
• 6502-CRT — the same idea for cartridge ROMs
• 6502-ASM — worked assembly examples
• 6502-DOCS — the documentation site: the cross-development and assembly guides, and the printable reference cards
• cffs / bin2woz — the tools behind make cf and make woz

License

MIT License — see LICENSE.