Z80neo

z80neo

          ████   ████                             
         █░░░ █ █░░░██                            
  ██████░█   ░█░█  █░█ ███████   █████   ██████   
 ░░░░██ ░ ████ ░█ █ ░█░░██░░░██ ██░░░██ ██░░░░██  
    ██   █░░░ █░██  ░█ ░██  ░██░███████░██   ░██  
   ██   ░█   ░█░█   ░█ ░██  ░██░██░░░░ ░██   ░██  
  ██████░ ████ ░ ████  ███  ░██░░██████░░██████   
 ░░░░░░  ░░░░   ░░░░  ░░░   ░░  ░░░░░░  ░░░░░░    

A computer built around a real Z80 CPU.

z80neo is not an emulator. A genuine Zilog Z0840004 (NMOS, TTL-level) runs real code, while an Olimex RP2350-PICO2-BB48 (RP2350B, 48 GPIOs) acts as its RAM, ROM and all of its I/O. The Pico captures the Z80 bus cycle-by-cycle through PIO, services each access and stalls the CPU with WAIT — so the two chips share one bus exactly like a classic microcomputer.

On top of that it emulates an MMU, a serial console (and a second UART), a 15-drive CP/M sector disk, an OLED status display, a keypad menu, and it drives an optional FPGA VDP over SPI. It boots CP/M 2.2, Fuzix and bare-metal Z80 programs from an SD card.

• Website / source: https://github.com/turboss/z80neo
• Console: UART0, 115200 8N1 (GPIO0/1), shared by the firmware and CP/M
• Storage: SD card (FatFS) holding the OS images, disk images and Z80NEO.INI

Features

• Real Z80, no emulation — the Pico is bus master/slave only; the Z80 executes every instruction.
• Full memory + MMU — four 16 KB banks (ram[4][16384]), optionally extended with PSRAM, behind a 4-page MMU on ports 0xF0–0xF3.
• Serial console on UART0 (0x80/0x81) plus an independent second UART (UART1, 0x90–0x93) with runtime-configurable baud/format.
• CP/M 2.2 with 15 emulated sector disks (A:–O:) from CPMDISK0..14.IMG.
• SD-card file API for bare-metal programs (0xA0–0xA7), with directory walking into subdirectories.
• Firmware-side Standard MIDI File player streaming to a UART1 MIDI out, with a live VT102 channel monitor.
• SSD1306 OLED status display + ADC keypad menu, with an idle screensaver.
• VoidVDP / NullVDP support — a 640×256 bitmap console with an ESC g protocol, mirrored over SPI to an FPGA VDP.

Hardware

• CPU: Zilog Z0840004 (NMOS Z80, 4 MHz rated, run at ~128 kHz)
• Host: Olimex RP2350-PICO2-BB48 (RP2350B, 48-GPIO package, 16 MB flash)
• Z80 clock generated by PIO on GPIO32, reset on GPIO33
• SD card interface
• Serial port (UART0, 115200 8N1, GPIO0/1)
• Second UART on GPIO38 (TX) / GPIO39 (RX)
• SSD1306 OLED (I2C1) and an ADC keypad
• Optional NullVDP on an FPGA over SPI (GPIO34–37)

Schematics live in hardware/; see the pinout and datasheets in doc/.

Schematics

How it works

• Bus capture (PIO) — two PIO0 state machines watch MREQ and IORQ. On a cycle they assert WAIT, push a bus snapshot to the FIFO and block on PULL. The ARM core services the cycle, reads the address/data through the SEL1/2/3 mux and releases WAIT. Because the Z80 is stalled for the whole service time, timing is independent of the emulated clock speed.

• Memory / MMU — src/memory.c. 16-bit addresses map through mmu_page[] into the 16 KB banks; PSRAM can extend them.

• I/O ports — handled in io_read_port() / io_write_port():

  Port(s)	Function
  0x80/0x83	console data
  0x81	console status
  0x90/0x91	UART1 data / status
  0x92/0x93	UART1 baud code / line format config
  0x94/0x95	NullVDP console byte / link status
  0xA0–0xA7	SD-card file API (command, name, data, seek/size)
  0xD1	I2C EEPROM
  0xE0–0xE3	CP/M disk (data/command, track, sector/status, drive select)
  0xF0–0xF3	MMU page select

• Clock / reset — src/z80clock.pio generates the Z80 clock; frequency (Z80_KHZ, 32..1000) and duty (Z80_DUTY, 5..95 %) are settable from Z80NEO.INI.

• Display / keys — core 1 drives the OLED and the debounced ADC keypad menu; core 0 owns the bus loop and UARTs.

• Boot — mount SD → read Z80NEO.INI → load the Intel HEX program into banks → hold reset → start PIO → release reset.

See AGENTS.md for an in-depth description of every subsystem and the hardware/timing gotchas.

Build the firmware

Requires the Raspberry Pi pico-sdk 2.x and an arm-none-eabi toolchain. firmware/build.sh hardcodes the local SDK paths — edit it for your setup.

cd firmware
./build.sh            # cmake -B build -S . -DPICO_BOARD=z80neo_bb48 -DPSRAM_ENABLE=ON

The output ELF is firmware/build/z80neo/z80neo.elf. Build with PICO_BOARD=z80neo_bb48, never pico2 — pico2 is the RP2350A (30 GPIOs), so GPIO30–47 (clock, reset, keypad) are silently dropped. main.c #errors on the wrong package.

Flash over CMSIS-DAP/OpenOCD:

cd firmware
./upload.sh           # openocd ... program build/z80neo/z80neo.elf verify reset exit

Debug (OpenOCD + GDB):

cd firmware
./debug.sh            # standard gdbinit
./debug.sh serial     # serial-tracing gdb script

There is no unit-test framework; verify by building, flashing and watching UART0 (115200 8N1) plus the OLED. tools/z80_boot_sim.py is the only offline harness. The full pipeline — firmware + OS + SD deploy — is ./build_all.sh.

SD card

Copy sdcard/Z80NEO.INI, your program image and the CP/M disk images to the card root. The preferred INI format is order-independent KEY=VALUE:

The default sdcard/Z80NEO.INI boots CP/M. Program images are Intel HEX — both the .hex (CP/M) and .ihx (z88dk) spellings load.

Software

• CP/M 2.2 — software/cpm/z80neo/, built with make into build/cpmz80neo.hex. CCP/BDOS at 0xD400, BIOS at 0xEB00; 15 sector disks A:–O: from CPMDISK0..14.IMG. CP/M disk helpers live in tools/ (pack_cpm_collection.py, install_cpm_disks.py) and the PySide6 TBCPMTools GUI can inspect/edit the images.
• Fuzix — software/Fuzix/, an FCC-built banked kernel.
• CP/M software — software/cpm/ also holds turboterm/ (TTERM.COM, bridges the CP/M console to UART1), the midiplayer/, a regulus-radiant-crucible/ Forth, and the te/ editor sources.
• BASIC — BBC BASIC (software/bbcbasic{, -z80}/) and software/Tiny-Basic-Z80/.
• Bare-metal C (zcc +z80neo) — the in-tree z88dk target links at ORG 0x0000, owns page 0 and uses ports 0x80/0x81. It ships a bitmap graphics layer (z80neo_gfx_*) speaking the VDP ESC g protocol. See software/z80neo/.
• MON — software/z80neo/monitor/, a full machine monitor/debugger (dump/edit, disassemble, breakpoints, single-step, HEX load, MMU control).
• MIDI player — software/z80neo/midiplayer/ (bare metal) and software/cpm/midiplayer/ (MIDI.COM): SD-card Standard MIDI File players driving UART1 at 31250 baud, with a firmware-side SMF parser and monitor.
• Assembly tests — software/asm/, built with z88dk (./build_hex.sh <name>).

Assembly example

PORT_LEDS: equ 0x40
VAL_A equ 0xBA
VAL_B equ 0xAB

main:
  ld	sp, 0x3fff

loop:
  ld    A, VAL_A
  out	(PORT_LEDS), A

  ld    A, VAL_B
  out	(PORT_LEDS), A

  JP	loop

topOfStack

Companions

• VoidVDP (vdp/) — a fork of VersaTerm used as a standalone RP2350/RP2040 VGA serial terminal (a separate board). Talks over UART1 and implements the console protocol in doc/vdp_protocol.md.
• NullVDP (vdp/NullVDP/) — a Verilog VDP on a Sipeed Tang Primer 20K FPGA with HDMI output, spoken to over SPI by the firmware.
• sdl_client (sdl_client/) — a PC-side SDL3 VT100/VT102 terminal for /dev/ttyACM0, including the ESC g bitmap layer.

Pictures

the thing

back wiring

pulse view capture

display

serial out

Community

Join the live chat:

• Matrix: https://matrix.to/#/#z80neo:jauriarts.org
• Discord: https://discord.gg/TQudWKCKCQ
• IRC: https://web.libera.chat/ #z80neo

References

• picoram6116 — https://github.com/lambdamikel/picoram6116
• Agonlight - https://www.thebyteattic.com/p/agon.html
• Neo6502 — https://neo6502.com/

License

• Hardware: CERN Open Hardware Licence Version 2 — Strongly Reciprocal
• Software: GPL v3
• Documentation: CC BY-SA 4.0