This is a template, written in Verilog, for Z80 computers running on the Ulx3s Ecp5 open source FPGA board.
It is intended to be used as a starting point for building a variety of Z80 retro computers and games consoles, including:
- The TRS-80 Model 1, and the Video Genie clone of it
- The Sinclair ZX80 and ZX81
- The Jupiter Ace
- The Sinclair ZX Spectrum
- The Galaksija Croatian kit computer
- The Amstrad CPC
- The Amstrad PCW
- MSX computers and the Spectravideo sv-318, on which they are based
- The Colecovision and the similar Sega SG 1000 games console
- The Sega Master System games console and the similar Sega Game Gear portable console
It can also be used to create generic Z80 computer running CP/M and/or Microsoft Basic, or monitor programs such as the Small Computer Monitor.
It could also be used as a basis for 8080 computers such as the Altair 8800, and for the Ninendo Game Boy that uses a variant of the Z80.
The template is configurable using parameters to the top level Verilog module (top.v).
Further configuration is done by modifying this top level module and adding extra modules as needed by each computer or console.
The CPU is based on the TV80 8-Bit Microprocessor Core by Guy Hutchison (ghutchis@opencores.org), which ia a conversion of the VHDL T80 core by Daniel Wallner (jesus@opencores.org).
The system clocks are generated using ecp5_pll, written by @emard.
A configurable power-on reset is generated, and reset can also be done using the Ulx3s reset button (button 0), and can be done remotely from the ESP32.
The CPU clock speed is set from an enable signal derived from a clock generated by ecp5_pll.
There are options to use either on-chip RAM or external SDRAM, or a combination of both, to support RAM and ROM memories.
By default 64kb of RAM is available and ports 80 and 81 can be configured for the uart.
Each computer or console needs its own specific address decoding, I/O ports and cpu data in multiplexing.
There is amn optional UART implemented using a Motorola 6850 ACIA Verilog module, converted to the Ulx3s by Paul Ruiz.
There is am optional video module that generates a VGA signal that can be fed into a VGA Pmod (such as the Digilent or the Goran Mahovlic ones), or which can be converted to an HDMI signal using a TMDS decoder module.
It is assumes that ESP32 co-processor on the Ulx3s board is running micropython, but this is only used in some configurations.
There is an optional SPI read/write memory slave implementation which allows memory to be wroitten, and the CPU to be controlled, from an SPI Master written in micropython on the ESP32. This can be accesssed via micropython repl, including web repl from a browser.
Built on top of the SPI slave is an optional On-Screen Display (OSD), for selecting roms or program files to be loaded and run, using a file broswer overlaid on the vide output.
The OSD typically loads roms and programs from an SD card, but can use the ESP32 flash memory.
The OSD software is written in micropython.
The Ulx3s buttons can be used to control the OSD and as a simple joypad emulator for games consoles.
An ST7789 7 or 8 pin SPI display can be connected to the Ulx3s Oled header and used for showing diagnostic information in hex.
The row of 8 leds on the Ulx3s can be used for status values or diagnostics.
Extra leds are supported for diagnostics, typically by 2 Digilent 8 led Pmods.
A PS/2 keyboard can be configured that producers an 11-bit PS/2 key value. The decoding of this is done by a machine-specific ketboard module.
a PS/2 mouse can also be supported, where required.
USB game controllers can be added, where needed.
Audio is device-specific and can be added using extra audio Verilog modules.
To build, you need a recent version of yosys, nextpnr-ecp5, project trellis and fujprog.
After cloning the repository, do:
cd ulx3s
make prog
By default, the roms/boot.asm monitor runs.
You can connect to this by
screen /dev/ttyUSB0 9600
or use any other terminal emulator.
You can also run software compatiblle with the RC2014, such as roms/R0000009.BIN.
To run this upload osd/osd.py, osd/ld_nes.py, and roms/R0000009.BIN to the esp32 and in web repl do:
import osd
You can then start the OSD by pressing all 4 direction buttons, select the R0000009.BIN file by navigating with the up and down buttons, and selecting with the right button.
This will upload R0000009.BIN and you should see Microsoft Basic start. You can run Basic programs using the uart.
There are 4 top-level directories: src, esp32, roms and ulx3s.
The src directory contains all the Verilog source including the top-level file: top.v.
There are then subdirectories for all the components:
- video for VGA and HDMI output
- uart for the ACIA uart
- keyboard for the ps/2 keyboard module
- memory for BRAM and SDRAM components
- lattice for Lattice ECP5 specific code, which implements the PLL
- Z80 for the TV80 CPU
- spi_display for the LCD hex diagnostics
- osd for the OSD
The esp32 directory contains micropython code that controls the OSD and needs to be uploaded to the ESP32.
The roms directory contains roms that can be uploaded to the ESP32 and run, such as R0000009.BIN.
It also contains what you need to build your own rom using Z80 assembler.
The example rom is called boot.asm. It is compiled with vasmz80_oldstyle, which you should move to somewhere on the PATH, such as /usr/local/bin.
You can then build boot.bin and boot.hex from boot.asm, using build.sh.
The ulx3s directory contains the Makefile for building a Ulx3s ECP5 bitstream, and includes ulx3s.mk used by the Makefile and the lpf file that defines the pin settings.