Like 0

Revision 25c06fb366780743606bc635f8e6eb3032a781e2

Portable65 – Full Project Description.md Raw

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 calls pio_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.96 gives ~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)

  1. stdio_init_all() (USB; UART disabled in CMake).
  2. Initialise expander, keyboard, mapper, CPU GPIO and video (display, TMS).
  3. “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.
  4. cpu_clk_enable() – hand the pins over to the PIO program and start the clock.
  5. 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

  1. The 6502 program writes to $8002/$8003 just as it would to a real TMS9918.
  2. video.c forwards this to vrEmuTms9918*, a library by Troy Schrapel (MIT licence) that emulates the VDP: Graphics I/II, Text and Multicolor modes, sprites, VRAM.
  3. video_cycle() generates one 256-pixel line via vrEmuTms9918ScanLine(), 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).
  4. 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

  1. Assembler: tools/asm2bin.sh file.a65 (ca65 and ld65 from the cc65 package, -t none config) produces .obj .lst .map .bin. The .bin is exactly 32,512 bytes and maps to $8100–$FFFF.
  2. tools/bin2rom file.bin writes rom.h in the current directory (const uint8_t ROM_CONTENT[32768-256]). Copy it into include/.
  3. Pico firmware: CMake + pico-sdk (PICO_SDK_PATH must be set), Release build, output p65.uf2, stdio over USB.
  4. tools/p65tok tokenises BASIC programs (from stdin) and generates the C array ram_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.

  1. 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.
  2. 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.
  3. Sound not implemented. The ROM writes to $8008/$8009 (AY-3-8910); the mapper ignores those writes.
  4. mapper_read() has no final return (compiler warning). Reads from unused I/O registers return 0.
  5. A forbidden ROM write does a printf on core 1, which slows the bus, and “RESTRICTED WRITE” will spam the console when a program misbehaves.
  6. Hard-coded pins (17, 28) in video.c, even though ili9341_config has fields for them. The comment about CS being high in ili9341_init_gpio() disagrees with the code (gpio_put(cs, 0)). CS is held low for the entire frame.
  7. 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.
  8. 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.
  9. CPU reset is done the hard way (the author called it crappy) and busy-waits for I²C writes.
  10. The repository contains clutter: build/, .obj/.lst files, a duplicate key2led.s, compiled tool binaries. There is no README, schematic or .gitignore.

12. Getting back to work

  1. Install pico-sdk (set PICO_SDK_PATH), the arm-none-eabi-gcc toolchain, CMake and cc65.
  2. Delete the old build/ (it contains paths from the old machine) and build from scratch: mkdir build && cd build && cmake .. && make.
  3. Check the hardware step by step with simple ROMs: blinker (LEDs) → key2led (keyboard) → vdp (display) → testrom1 (everything).
  4. Remove the printf from video_cycle() and measure the frame rate.
  5. Sensible next steps: a VDP VSYNC interrupt (IRQ line), AY-3-8910 emulation (sound, e.g. PWM/PIO), saving/loading BASIC programs (SAVE/LOAD over 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.