Tridora-CPU/README.md

# Tridora-CPU
The Tridora-CPU is a homebrew CPU written in Verilog and a matching software environment,
including a Pascal compiler and assembler.
Everything was created from the ground up (except soldering stuff).
Everything is as simple as possible while still being reasonably useful.
Everything is open source, so you can read, understand and modify the whole system, hardware and software.

## Overview
- homebrew CPU written in Verilog implemented on an FPGA
- 32-bit word-oriented stack machine architecture
- running at 77 MHz on an Arty-A7 board with four clocks per instruction
- has its own instruction set architecture, compatible with nothing
- additional IO controllers on FPGA: UART (serial console), SD-Card, VGA
- Pascal compiler written from zero
- CPU and compiler were designed together
- minimal operating system
- editor, compiler, assembler run natively
- so you can develop programs directly on the machine
- small: CPU has ~500 lines of Verilog, compiler ~9000 LoC
- compiler written in Pascal and can compile itself
- cross-compiler/-assembler can be compiled with FPC
- compiler does its own Pascal dialect with some restrictions and some extensions
- emulator available [here](https://gitlab.com/slederer/Tridora-CPU/-/tree/main/tridoraemu)

The name comes from a certain fictional monster with three heads. The prefix tri- is greek for three, and the Tridora-CPU
has three stacks instead of just one like almost all other CPUs.
It also
has a strange mixture of features from three different eras of computing:
- a simple instruction set without integer multiply/divide like an 8-bit CPU
- speed is like a fast 16-bit CPU, also 16-bit instruction words
- 32-bit word size from the 32-bit era

It might remind you of the UCSD-P-System and early Turbo-Pascal versions.

Other inspirations were, among others, in no particular order:

- the Novix 4016 CPU (a stack machine CPU designed for Forth, mainly by Charles Moore)
- the J1 CPU by James Bowman (which is not entirely unlike the Novix 4016)
- the Lilith computer by Niklaus Wirth and his team (a stack CPU designed for Modula-2)
- the PERQ workstation (also a stack CPU designed for Pascal)
- the Magic-1 by Bill Buzbee
- the OPC by revaldinho

## October 2025 Update
This update introduces a data cache for the Tridora-CPU. It is similar to the instruction cache
as it caches the 16 bytes coming from the DRAM memory controller. It is a write-back cache, i.e.
when a word inside the cached area is written, it updates the cache instead of invalidating it.

This is important because there are many idioms in the stack machine assembly language where you
store a local variable and then read it again (e.g. updating a loop variable).

Since for most programs, the user stack and parts of the heap are inside the DRAM area, the data cache
has a more noticable impact. In the benchmark program that was already used for the last update,
the data cache results in a 50% improvement for the empty loop test. This is in comparison to the version
without data cache but with the instruction cache, both running code out of DRAM.

It is also noticable for compile times: With the data cache, compiling and assembling the
"hello,world" program takes 16 seconds instead of 20. With a little tweak of the SD-Card controller
that slightly increased the data transfer rate, the build time goes down to 15 seconds.

Also, an audio controller was added that allows interrupt-driven sample playback via an AMP2 PMOD.

## April 2025 Update
The clock has been reduced to 77 MHz from 83 MHz. Apparently the design was at the limit and
timing problems were cropping up seemingly at random. Reducing the clock speed made some
enhancements and bugfixes possible. Also, the project files work with Vivado 2024 now.

Most importantly, the Tridora-CPU now has an instruction cache with a size of 16 bytes or eight instructions.
This increases execution speed when running code out of DRAM (that is, above 64KB). In a simple
benchmark program, the CPU is about twice as fast.
Many programs fit into the lower 64KB of RAM, which can be accessed without latency, and will
have no noticable speed increase.

There have also been a number of bug fixes for the compiler and some for the assembler. This makes
compiling even larger and more complex programs possible. An example of this is ECL-Rogue, a variant of Rogue written
Pascal, which has been ported to Tridora-Pascal and is now included
on the emulator image.

## Links/Downloads
- the [source repository](https://gitlab.com/slederer/Tridora-CPU)
- the [Hackaday project](https://hackaday.io/project/198324-tridora-cpu) (mostly copy-paste from this README)
- the [YouTube channel](https://www.youtube.com/@tridoracpu/videos) with some demo videos
- the [emulator](https://git.insignificance.de/slederer/-/packages/generic/tridoraemu/0.0.5/files/12) (source and windows binary)
- the [FPGA bitstream](https://git.insignificance.de/slederer/-/packages/generic/tdr-bitstream/0.0.4/files/16) for the Arty-A7-35T board
- an [SD-card image](https://git.insignificance.de/slederer/-/packages/generic/tdr-cardimage/0.0.4/files/13)

Contact the author here: tridoracpu [at] insignificance.de

You can also open a ticket on Gitlab or send a message on Hackaday.

## Demos
### Videos

|Compiling and Running "Hello World"|Moving Lines Demo|
|---|---|
[![image](https://insignificance.de/tridora/tdr-hello-thumb.jpg)](https://youtu.be/JXUnOOe_fVg)|[![image](https://insignificance.de/tridora/tdr-lines-thumb.jpg)](https://youtu.be/Y8Bx2Bsyu88) |

### Pictures

|Mandelbrot|Image Viewer|Game of Life|
|---|---|---|
|![image](https://insignificance.de/tridora/tdr-mandelbrot.jpg)| ![image](https://insignificance.de/tridora/tdr-ara.jpg) | ![image](https://insignificance.de/tridora/tdr-conway.jpg) |

## Supported FPGA Boards
### Arty-A7-35T
At the moment, the only supported board is the Digilent Arty-A7-35T.

Two Pmods are used for a complete system:

- the Digilent MicroSD Pmod at the JA connector
- the Digilent VGA Pmod at the JB and JC connectors

As the Arty-A7-35T is no longer in production, it should be easy to
use the Arty-A7-100T instead, but this has not been tested yet.

Other boards under consideration are the Digilent Nexys-A7 and the Arty-S7.

## Pascal Language
- Wirth Pascal
- no function types/parameters
- arbitrary length strings (2GB)
- safe strings (runtime information about max/current size)
- tiny sets (machine word sized), that means no SET OF CHAR
- array literals with IN-operator, which can replace most uses of SET OF CHAR
- nested procedures
- 32 bit software floating point with low precision (5-6 digits)
- break and exit statements, no continue yet
- static variable initialization for global variables
- non-standard file i/o (because the standard sucks, obl. XKCD reference)

## Standard Library
- everything from Wirth Pascal
- some things from TP3.0
- some graphics functionality (to be expanded in the future)

## Operating System
- not a real operating system, more of a program loader
- some assembly routines for I/O resident in memory
- one program image loaded at a time at a fixed address
- most parts of the operating system are contained in the program image
- file system is very primitive: only contiguous blocks, no subdirectories
- simple shell reminiscent of TP3.0, edit, compile, run programs

## Building the Compiler
- you need to have _FPC_ and _Python3_ installed
- on Linux, you need _make_ installed
- in the **pcomp** directory, run **make** (or **make.bat** on Windows)
- on Linux, you can also run **make nativeprogs** and **make examples**

## Getting the ROM image
- there are two formats for the ROM image, one for the emulator (**rommon.prog**) and one for building the FPGA bitstream (**rom.mem**)
- to get the **rommon.prog** file, either copy it from the _tridoraemu_ package file or build it
- for **rom.mem** and **rommon.prog**, find both files in the **lib** directory after running **make nativeprogs** (or **make.bat**) in the **pcomp** directory (see above)

## Building the FPGA bitstream
- install Vivado (April-2025-Update tested with 2024.2)
- install the package for your board in Vivado (Tools -> Vivado Store -> Boards)
- copy the ROM image (**rom.mem**) into the **tridoracpu** directory (see above)
- start Vivado and open the project file **tridoracpu.xpr** in the **tridoracpu** directory
- run synthesis, implementation and bitstream generation (Flow -> Generate Bitstream)
- program your device (Flow -> Open Hardware Manager), the bitstream file should be in **tridoracpu/tridoracpu.runs/impl_1**
- the bitstream file for (temporarily) programming your device is named **top.bit**, the file for flashing your device is named **top.bin**

## Running the Emulator
See the emulator [README](tridoraemu/README.md).

## Documentation
- [Instruction Reference](doc/tridoracpu.md)
- [Memory Layout](doc/mem.md)
- [UART](doc/uart.md)
- [SD-Card controller](doc/spisd.md)
- [VGA controller](doc/vga.md)
- [Using the Shell](doc/shell.md)
- [The Mostly Missing Pascal Programming Guide](doc/pascalprogramming.md)

More documentation is coming, as time permits.

## Credits
The Tridora-CPU uses the UART from the J1 CPU by James Bowman (*uart.v*), see https://github.com/jamesbowman/j1

The VGA framebuffer uses code from Project F by Will Green, see https://projectf.io