# 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. Idea](#idea)[2. Hardware](#hw)[3. Memory map](#mem)[4. Bus & PIO](#bus)[5. Cores](#cores)[6. Keyboard](#kbd)[7. Video](#vid)[8. ROM & BASIC](#rom)[9. Tools](#tools)[10. Files](#files)[11. Issues](#issues)[12. Getting back to work](#resume) ## 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.