awesome-copilot/skills/legacy-circuit-mockups/references/assembly-compiler.md

6502 SBC Assembly Compilation & ROM Build Specification

Overview

This document defines a complete specification for compiling 6502 assembly language for a single-board computer consisting of:

• MOS 6502 CPU
• MOS 6522 VIA
• AS6C62256 (32 KB SRAM)
• AT28C256 (32 KB EEPROM / ROM)
• DFRobot FIT0127 (HD44780-compatible 16x2 LCD)

The focus is on toolchain behavior, memory layout, ROM construction, and firmware conventions, not electrical wiring.

---

Target System Architecture

Memory Map (Canonical)

$0000-$00FF  Zero Page (RAM)
$0100-$01FF  Stack (RAM)
$0200-$7FFF  General RAM (AS6C62256)
$8000-$8FFF  6522 VIA I/O space
$9000-$FFFF  ROM (AT28C256)

Address decoding may mirror devices; assembler assumes this canonical layout.

---

ROM Organization (AT28C256)

Address	Purpose
$9000-$FFEF	Program code + data
$FFF0-$FFF9	Optional system data
$FFFA-$FFFB	NMI vector
$FFFC-$FFFD	RESET vector
$FFFE-$FFFF	IRQ/BRK vector

ROM image size: 32,768 bytes

---

Reset & Startup Convention

On reset:

1. CPU fetches RESET vector at $FFFC
2. Code initializes stack pointer
3. Zero-page variables initialized
4. VIA configured
5. LCD initialized
6. Main program entered

---

Assembler Requirements

Assembler MUST support:

• .org absolute addressing
• Symbolic labels
• Binary output (.bin)
• Little-endian word emission
• Zero-page optimization

Recommended assemblers:

• ca65 (cc65 toolchain)
• vasm6502
• 64tass

---

Assembly Source Structure

;---------------------------
; Reset Vector Entry Point
;---------------------------
        .org $9000
RESET:
        sei
        cld
        ldx #$FF
        txs
        jsr init_via
        jsr init_lcd
MAIN:
        jsr lcd_print
        jmp MAIN

---

Vector Table Definition

        .org $FFFA
        .word nmi_handler
        .word RESET
        .word irq_handler

---

6522 VIA Programming Model

Register Map (Base = $8000)

Offset	Register
$0	ORB
$1	ORA
$2	DDRB
$3	DDRA
$4	T1CL
$5	T1CH
$6	T1LL
$7	T1LH
$8	T2CL
$9	T2CH
$B	ACR
$C	PCR
$D	IFR
$E	IER

---

LCD Interface Convention

LCD Wiring Assumption

LCD	VIA
D4-D7	PB4-PB7
RS	PA0
E	PA1
R/W	GND

4-bit mode assumed.

---

LCD Initialization Sequence

lcd_init:
        lda #$33
        jsr lcd_cmd
        lda #$32
        jsr lcd_cmd
        lda #$28
        jsr lcd_cmd
        lda #$0C
        jsr lcd_cmd
        lda #$06
        jsr lcd_cmd
        lda #$01
        jsr lcd_cmd
        rts

---

LCD Command/Data Interface

Operation	RS	Data
Command	0	Instruction
Data	1	ASCII character

---

Zero Page Usage Convention

Address	Purpose
$00-$0F	Scratch
$10-$1F	LCD routines
$20-$2F	VIA state
$30-$FF	User-defined

---

RAM Usage (AS6C62256)

• Stack uses page $01
• All RAM assumed volatile
• No ROM shadowing

---

Build Pipeline

Step 1: Assemble

ca65 main.asm -o main.o

Step 2: Link

ld65 -C rom.cfg main.o -o rom.bin

Step 3: Pad ROM

Ensure rom.bin is exactly 32768 bytes.

---

EEPROM Programming

• Target device: AT28C256
• Programmer: MiniPro / T48
• Verify after write

---

Emulator Expectations

Emulator must:

• Load ROM at $9000-$FFFF
• Emulate VIA I/O side effects
• Render LCD output
• Honor RESET vector

---

Testing Checklist

• Reset vector execution
• VIA register writes
• LCD displays correct text
• Stack operations valid
• ROM image maps correctly

---

References

• MOS 6502 Programming Manual
• MOS 6522 VIA Datasheet
• AT28C256 Datasheet
• HD44780 LCD Datasheet
• cc65 Toolchain Docs

---

Notes

This specification is intentionally end-to-end: from assembly source to EEPROM image to running hardware or emulator. It defines a stable contract so ROMs, emulators, and real SBCs behave identically.