Portable65
A portable 8-bit computer built around a real WDC 65C02 CPU, where a Raspberry Pi Pico (RP2040) plays “everything else”: memory, a TMS9918 video chip, keyboard and clock generator. This description is based on analysis of the code in Portable65.zip (files dated February–October 2024).
1. Idea2. Hardware3. Memory map4. Bus & PIO5. Cores6. Keyboard7. Video8. ROM & BASIC9. Tools10. Files11. Issues12. Getting back to work
1. Project idea
A real 65C02 is wired directly to the Pico’s GPIO. The Pico does not emulate the CPU. Instead it emulates everything around it, cycle by cycle, in real time:
- it supplies the PHI2 clock (a PIO program),
- it samples address and data from the bus, and on reads drives the requested byte onto the data lines,
- it pretends to be 32 KB of RAM, ~32 KB of ROM and a few I/O registers,
- it emulates a TMS9918 graphics chip in software (using the vrEmuTms9918 library) and shows the picture on an ILI9341 display,
- it scans the keyboard matrix through a PCAL6524 I²C expander, which also drives the LEDs and the CPU’s RESET/IRQ/NMI lines.
In short: an Apple II/Apple-1-style machine (keyboard with bit 7 as a strobe, Monitor + mini-assembler, Applesoft-like BASIC) with TI-99/MSX/ColecoVision-style graphics (TMS9918), built from a 65C02, a Pico and an SPI display.
2. Hardware (inferred from the code)
| Part | Role | Evidence in code |
|---|---|---|
| Raspberry Pi Pico (RP2040, 125 MHz) | All logic around the CPU | PICO_BOARD=pico, PICO_PLATFORM=rp2040 in CMakeCache; set_sys_clock_khz is commented out, so default 125 MHz |
| WDC 65C02 | CPU | 65c02.* files, ROM uses 65C02 instructions (.pc02) |
| ILI9341 320×240, SPI0 | Display (256×192 window, centred) | ili9341.c, MADCTL = 0xA8 (landscape, BGR) |
| NXP PCAL6524 (I²C1, address 0x22) | 24-bit expander: keyboard matrix, LEDs, CPU control lines | pcal6524.c, keyboard.c |
| Address latches/buffers | Multiplex A0–A15 onto 8 GPIO lines | signals CPU_B0_EN and CPU_B1_EN (buffers are selected one after the other) |
| 7×8 keyboard + 3 LEDs | User input | tables r0..r6 in keyboard.c |
There is no electrical schematic in the archive. The above is reconstructed from code, so exact buffer part numbers (e.g. 74HC245/573) are a guess.
RP2040 pin assignment
| GPIO | Signal | GPIO | Signal |
|---|---|---|---|
| 0–7 | Address bus (A0–A7 or A8–A15, depending on the enabled buffer) | 20 | B0_EN – enables low address byte buffer |
| 8–15 | Data bus D0–D7 | 21 | B1_EN – enables high address byte buffer |
| 16 | CPU R/W (1 = read) | 22 | PHI2 clock (side-set from PIO) |
| 17 | LCD CS | 26 / 27 | I²C1 SDA / SCL (1 MHz) |
| 18 / 19 | SPI0 SCK / MOSI | 28 | LCD D/C |
PCAL6524 expander – port 2 (control)
| Bit | Function |
|---|---|
| 0 | CPU_RST |
| 1 | CPU_IRQ |
| 2 | CPU_NMI |
| 3 | LCD_RST (kept high) |
| 5–7 | LED0–LED2 (inverted logic) |
Port 0 carries the keyboard columns (inputs with pull-downs); port 1 carries the rows (outputs).
3. Memory map
| Range | Contents | Implementation (mapper.c) |
|---|---|---|
$0000–$7FFF |
32 KB RAM | RAM[32768] array in Pico SRAM |
$8000–$80FF |
I/O (256 bytes) | mapper_io_read/write |
$8100–$FFFF |
ROM, 32,512 bytes | copy of ROM_CONTENT from rom.h in SRAM (memcpy at start-up); writes are rejected |
I/O registers
| Address | Read | Write |
|---|---|---|
$8000 |
LED state | Sets LEDs (bits 0–2) |
$8001 |
Last key; bit 7 = new key (Apple II convention) | Any value clears bit 7 (like $C010) |
$8002 |
VDP: read VRAM | VDP: write VRAM |
$8003 |
VDP: status | VDP: write address / register |
$8008/$8009 |
not implemented the ROM writes here for an AY-3-8910 (sound), but the mapper does nothing with it |
Vectors: NMI and RESET point to entry ($F40E), IRQ to $F6D7.
4. The bus and the PIO program
This is the most interesting part of the project. 65c02_clk.pio is only 12 instructions long and handles one complete bus cycle:
start: set pins,0b10 side 1 [2] ; PHI2=1, select A0-A7 buffer
in pins,8 ; capture A0-A7
set pins,0b01 [2] ; switch to A8-A15 buffer
in pins,24 ; capture A8-A15, D0-D7, R/W (+ rest)
jmp pin read ; R/W=1 => read
nop side 0 [4] ; write: PHI2=0, pad path length
jmp start
read: mov osr,~null
out pindirs,8 ; data pins become outputs
out pins,8 [1] ; autopull waits for core1's byte, then drives it
mov osr,null
out pindirs,8 side 0 ; data pins back to inputs, PHI2=0
One 32-bit word arrives through the FIFO: bytes 0–1 are the address, byte 2 is data, bit 24 is R/W. Core 1 decodes it in cpu_cycle().
- Read: the PIO stalls on
out pins(autopull from an empty TX FIFO). The clock stays high until core 1 callspio_sm_put(mapper_read(addr)). The 65C02 is a static design, so it simply waits. - Write: the PIO does not wait; it pushes the word to the RX FIFO and core 1 performs
mapper_write. - Clock rate:
clkdiv = 4.96gives ~25.2 MHz for the PIO. A bus cycle takes 15 PIO ticks, so the CPU clock comes out at about 1.7 MHz (my estimate from the code, not a measurement). The 4.960 divider looks empirically tuned.
5. How the two cores split the work
| Core | Tasks |
|---|---|
| Core 1 | The cpu_cycle() loop: blocking reads from the PIO FIFO, memory and I/O handling. Has bus priority (bus_ctrl_hw->priority = PROC1). |
| Core 0 | Main loop: keyboard_scan() (non-blocking state machine) and video_cycle() (one scanline per iteration), plus debug printf. |
Start-up sequence (main.c)
stdio_init_all()(USB; UART disabled in CMake).- Initialise expander, keyboard, mapper, CPU GPIO and video (display, TMS).
- “Crappy CPU reset”: RESET via expander port 2, two manual clock pulses on the GPIO pin (a CPU in reset needs a few clocks), then release RESET.
cpu_clk_enable()– hand the pins over to the PIO program and start the clock.- Launch core 1 with
cpu_cycle(); core 0 enters the keyboard + video loop.
6. Keyboard
A 7-row × 8-column matrix (56 keys). Rows are set over I²C and columns are read back, all as a state machine (WRITE_ROW → WRITE_ROW2 → SCHEDULE_READ_COLUMN → READ_COLUMN → WRITE_P2) operating directly on the RP2040 I²C registers so that it does not block the video loop.
- Two character tables (normal and shifted). Ctrl masks the code to 5 bits (
& 0x1F). - Special codes: arrows 17/18, Ctrl = 130, Shift = 131.
- Hidden Ctrl+= shortcut calls
mapper_init_basic(): it writes a built-in demo program into RAM and sets the BASIC pointers ($67–$6A,$AF–$B0). - The same scan pass also writes LED state and CPU control lines (port 2).
Built-in demo program (reconstructed from tokens)
10 HGR
20 DEFSPR 0,255,129,129,129,129,129,129,255
30 DIM x(14),y(14)
40 FOR i=1 TO 14: x(i)=INT(RND(1)*256): y(i)=INT(RND(1)*192): NEXT
50 FOR i=1 TO 14: DRAW i,i+1,0,x(i),y(i): NEXT
60 FOR i=1 TO 14
70 x(i)=x(i)+(INT(RND(1)*3)-1): y(i)=y(i)+(INT(RND(1)*3)-1)
80 IF x(i)<0 THEN x(i)=0: ELSE IF x(i)>255 THEN x(i)=255
90 IF y(i)<0 THEN y(i)=0: ELSE IF y(i)>191 THEN y(i)=191
100 NEXT: IF PEEK($8001) AND 128 THEN GET a$: TEXT: END: ELSE GOTO 50
That is 14 square sprites wandering randomly across the screen (a TMS sprite test), ended by any key press.
7. Video
- The 6502 program writes to
$8002/$8003just as it would to a real TMS9918. video.cforwards this tovrEmuTms9918*, a library by Troy Schrapel (MIT licence) that emulates the VDP: Graphics I/II, Text and Multicolor modes, sprites, VRAM.video_cycle()generates one 256-pixel line viavrEmuTms9918ScanLine(), converts palette indices 0–15 to RGB565 (tmspal_bgr16, byte-swapped for SPI) and sends 512 bytes over SPI0 (100 MHz requested, ~62.5 MHz effective).- After 192 lines the frame ends. The ILI9341 window is set to columns 31–286 and rows 23–214, so the 256×192 picture sits in the middle of the 320×240 screen.
8. ROM and software
The ROM currently built in is testrom1.bin (I verified that include/rom.h is byte-for-byte identical to it). Banner string: P65 24030508 (apparently 2024-03-05, 08).
| Address | Contents |
|---|---|
$8100–$BFFF |
empty (zero-filled by .res) |
$C000… |
fpp65.a65: Applesoft-style BASIC (Microsoft BASIC per mist64/msbasic, adapted for this machine) |
$F000… |
Font and firmware: VDP init, text mode, cout/rdkey, scrolling, graphics hgrinit/plot, the Monitor (dump, go, registers, …) and a mini-assembler/disassembler (Apple II style) |
$FF00–$FF14 |
Jump table to system routines: vmon, vgetch, vputch, vclrscr, vclreol, vinitxt, vhgrini |
$FFFA–$FFFF |
NMI / RESET / IRQ vectors |
BASIC extensions (compared with Applesoft)
New commands: VDP, VPOKE, VPEEK, WPOKE, WPEEK, DEFSPR, DRAW, ELSE, SWAP, and $XX hex constants. HGR, HPLOT, HCOLOR= and TEXT are also defined (“more or less” working per the comments; HPLOT TO does not work). SAVE/LOAD are user vectors at $03D0/$03D3 and raise “Advanced Feature Error” by default.
Example programs (asm_examples/)
| File | What it is |
|---|---|
blinker |
Simplest test: loops a flashing pattern on the 3 LEDs via $8000 |
key2led |
Keyboard test: keys A/S/D light the LEDs (reads $8001) |
vdp |
TMS9918 test: register init, VRAM clear, font load |
goombas |
Sprite demo (animated “goombas”, code from Apple II TMS cards, addresses remapped to $8002/$8003) |
fpp65 |
BASIC + firmware source, assembled into testrom1 |
testrom1 |
The full ROM (.include "fpp65.a65") |
basic.a65 |
An earlier attempt: Lee Davison’s EhBASIC 2.22. Not used in the current ROM |
rom.bin |
An older ROM image (different from the current one) |
9. Tools and build process
- Assembler:
tools/asm2bin.sh file.a65(ca65 and ld65 from the cc65 package,-t noneconfig) produces.obj .lst .map .bin. The.binis exactly 32,512 bytes and maps to$8100–$FFFF. tools/bin2rom file.binwritesrom.hin the current directory (const uint8_t ROM_CONTENT[32768-256]). Copy it intoinclude/.- Pico firmware: CMake + pico-sdk (
PICO_SDK_PATHmust be set), Release build, outputp65.uf2, stdio over USB. tools/p65toktokenises BASIC programs (from stdin) and generates the C arrayram_basic_init[]. Its token table is tied to a specific ROM revision (“revision 24030415”); if the command list changes it must be kept in sync.
# typical workflow
cd asm_examples && ../tools/asm2bin.sh testrom1.a65
../tools/bin2rom testrom1.bin && mv rom.h ../include/
cd ../build && cmake .. && make # => src/p65.uf2, flash in BOOTSEL mode
10. File layout
| Path | Description |
|---|---|
src/main.c |
Start-up, CPU reset, core 0 loop, core 1 launch |
src/65c02.c, 65c02_clk.pio |
Clock and bus (PIO), cpu_cycle() |
src/mapper.c |
RAM/ROM/I/O, BASIC demo |
src/keyboard.c, pcal6524.c |
Keyboard matrix and I²C expander |
src/video.c, ili9341.c |
Screen emulation: scanlines → LCD |
src/tms9918.c, tms_util.c |
Third-party vrEmuTms9918 library (MIT) |
include/rom.h |
Generated ROM image (225 KB of text) |
asm_examples/ |
Sources and assembly output |
tools/ |
asm2bin.sh, bin2rom, p65tok (+ C sources) |
build/ |
CMake artefacts from 2024 (most of the 899 files in the archive); delete and regenerate |
11. Issues, risks and technical debt
Most important: video_cycle() calls printf for every scanline (192× per frame). Over USB stdio this is a huge slowdown, and with no listener it may block. Remove it first, before judging performance.
- Race between cores. The VDP object is written by core 1 (CPU writes) and read by core 0 (line generation) with no locking. Ctrl+= calls
mapper_init_basic()from core 0 while the CPU is running. At worst this gives minor visual glitches, but it is not formally correct. - No IRQ from VDP/keyboard. The IRQ/NMI lines exist on port 2, but nothing triggers them at run time. VDP status is only cleared on read, so programs get neither an interrupt nor a VSYNC flag.
- Sound not implemented. The ROM writes to
$8008/$8009(AY-3-8910); the mapper ignores those writes. mapper_read()has no finalreturn(compiler warning). Reads from unused I/O registers return 0.- A forbidden ROM write does a
printfon core 1, which slows the bus, and “RESTRICTED WRITE” will spam the console when a program misbehaves. - Hard-coded pins (17, 28) in
video.c, even thoughili9341_confighas fields for them. The comment about CS being high inili9341_init_gpio()disagrees with the code (gpio_put(cs, 0)). CS is held low for the entire frame. - Dead code:
draw_scanline,video_cycle2,cpu_poll,ili9341_lcdInit/lcdInit0,ili9341_drawBuffer, many commented-out blocks. The “SPI 0.5 MHz” comment is outdated. - CPU clock (~1.7 MHz by calculation) is tied to 125 MHz and
clkdiv 4.96. Changing the Pico clock (the commented-out 200 MHz) requires retuning the divider. - CPU reset is done the hard way (the author called it crappy) and busy-waits for I²C writes.
- The repository contains clutter:
build/,.obj/.lstfiles, a duplicatekey2led.s, compiled tool binaries. There is noREADME, schematic or.gitignore.
12. Getting back to work
- Install pico-sdk (set
PICO_SDK_PATH), thearm-none-eabi-gcctoolchain, CMake andcc65. - Delete the old
build/(it contains paths from the old machine) and build from scratch:mkdir build && cd build && cmake .. && make. - Check the hardware step by step with simple ROMs:
blinker(LEDs) →key2led(keyboard) →vdp(display) →testrom1(everything). - Remove the
printffromvideo_cycle()and measure the frame rate. - Sensible next steps: a VDP VSYNC interrupt (IRQ line), AY-3-8910 emulation (sound, e.g. PWM/PIO), saving/loading BASIC programs (
SAVE/LOADover USB or flash), a schematic and a README.
Static analysis only: I did not compile the project (no pico-sdk available) or run it on hardware. Behaviour descriptions come from reading the code; items marked as estimates or guesses are worth verifying on the device.