RISC-V Tetris

A computer inside the FPGA: a small RISC-V (RV32I) CPU written in Verilog, 32 KB of RAM, an 80 × 60 colour text screen and ten I/O registers. Then a toolchain for it, three Python files: an assembler, a small C compiler and an instruction-set simulator. Then Tetris, written in C, compiled by that compiler, running on that CPU on the board. The hardware was proven by running the same programs on the simulator and on the RTL and comparing every register write: identical over hundreds of thousands of instructions. New programs load over JTAG in six seconds, no rebuild.

No bitstream in the repo (a .sof is 3 MB per project): restore the .qar or use the sources here, one build makes it in about three minutes. The RAM is initialised with the Tetris program (assets/tetris.mif), so the board plays right after loading. The user guide has every command, including how to write and run your own program.

Contents

1. What you will see
2. Block diagram
3. The toolchain
4. How an instruction flows
5. The game
6. Numbers
7. How it was tested
8. Review log
9. Status and what is next
10. Files

What you will see

Power up: the title screen, PUSH START. Press Start (or KEY0): pieces fall into the 10 × 20 well. The joystick moves (held: auto-repeat), Up or A rotates, Down drops softly, B slams the piece down, Start pauses. Lines clear, the level rises every ten lines and the pieces fall faster; the buzzer clicks and chirps. All of it is C code running on the soft CPU at about 7 million instructions per second, updating once per video frame.

Block diagram

The toolchain

Everything a user needs is in the project folder and runs in the repo's env: no cross-compiler to download, nothing to install. The compiler accepts a C subset that is enough for games and drivers (its docstring lists exactly what, and it refuses the rest with a line number); the generated assembly is plain enough to read next to the C, which is the point of the course this BKM belongs to.

How an instruction flows

1. FETCH. The CPU puts pc on the bus with req. The RAM answers one clock later with ack and the word; it becomes ir.
2. EXEC. Everything is decoded from ir at once: the immediate, the two source registers, the ALU result, the branch condition, the next pc. ALU, branch and jump instructions finish here: the register is written (and a trace pulse tells the testbench), pc moves on, back to FETCH. Three clocks.
3. MEM for loads and stores: the data address goes on the bus (with byte enables for sb / sh); at the ack a load's byte or half is picked and sign- or zero-extended into the register. Five clocks.
4. The slaves. RAM, text RAM and I/O all answer in the same way (ack one clock after the request), so the decode is one case on addr[31:28]. The text RAM's second port is read by the screen 25 million times a second, independently.
5. The program waits for the frame counter to change, polls the buttons, updates the game, writes the cells that changed. Tetris uses a few per cent of the CPU; the rest is spent spinning on IO_FRAME.

The game

sw/tetris.c is 420 lines of the C subset: the seven pieces as 4 × 4 bit masks with four rotations, a 7-bag randomiser fed by the RANDOM register, collision tests, delayed auto-shift for held moves, soft and hard drop, line clearing with the classic 40 / 100 / 300 / 1200 points, a level every ten lines, speed from the level, the NEXT preview, pause, game over. Each well cell is 2 × 2 characters (16 × 16 pixels) drawn with the screen's block glyph in the piece's colour, with a darker quarter for a bevel; the well is redrawn only when something moved. The score goes to the 7-segment digits in BCD, the level to the LEDs, sounds to the buzzer as half-periods.

Numbers

How it was tested

The toolchain, on the simulator

• sw/test_isa.s: every instruction class, every load and store size, jumps, the screen and I/O registers, a loop; ends with EXIT 0 and prints OK on the UART.
• sw/test_c.c: 19 checks of the compiler: arithmetic with signs, the runtime multiply / divide / modulo, unsigned math, shifts, comparisons, casts, globals with initialisers, 2-D arrays, pointer arithmetic, recursion, eight arguments, every loop and switch, compound assignment, ++ / --, char wrap-around, macros, the screen and I/O macros. Each prints its number and ok / FAIL; the exit code is the number of failures: 0.
• tools/play_test.py: plays Tetris blind (random moves, a rotate, a hard drop per piece) for 60 pieces and checks the score grows, LINES counts a cleared row (seed 0x1d481499 clears one), LEVEL = LINES / 10, the digits hold the score in BCD, GAME OVER arrives. 10 s.

The hardware, in lock-step with the simulator

sim/tb_soc.sv runs the same images on the RTL CPU in Icarus and writes the same trace (every register write, every store). tools/trace_compare.py: ISA test identical, C suite identical, Tetris 294,803 lines identical. This is how the one real CPU bug was found in minutes: the arithmetic shift coming out logical. The testbench also dumps the UART text and the text screen, so a program's output can be read without a board.

On the board

Programmed, the title appeared (read back over USB). tools/load.py replaced the program in 6 s. Keys sent as USB letters started a game, moved and dropped pieces; the capture shows the well, the score (30) and the NEXT preview; the webcam shows the LCD and 000030 on the 7-segment digits.

Only a person can check

The joystick feel and the auto-repeat speed, the sounds, the pace of the levels, and the power cycle after a flash.

Review log

Status and what is next

Files