iCE2Tetris

Afternoon! Some of you will remember the heady days of 2014 when this club got together to work through the NAND to Tetris course. I still think it was one of my favourite club activities we ever did and I have a lot of fond memories of working through the book in the old Geckoboard office.

Late last year I decided to dip my toes into the FPGA world and bought myself an "iCEBreaker" board, which is a fairly cheap, entry-level FPGA that has the advantage of being entirely built on an open source toolchain, which means not having to deal with massive horrible IDEs from FPGA vendors, which had always put me off. I basically had zero experience with electronics but I'd been fascinated by FPGAs and wanted to learn more.

So naturally, when I received my iCEBreaker in February just a few weeks before lockdown began, I started learning enough about it that I could eventually aim to replicate the NAND to Tetris project on it. Just as we in the club developed a simulated computer out of CPU, RAM, ALU etc, I would do the same, except on real hardware. I hooked up the FPGA to a VGA display, and for input I implemented the PS/2 protocol and found an old keyboard online.

After months of hard work, I have now open sourced my project, which can be found here: https://github.com/leocassarani/ice2tetris. The repository also includes a C++ simulator (in the sim directory) which allowed me to try out the hardware design without running it on real hardware -- this involved (for example) taking key presses on my Mac and translating them into PS/2 signals so the simulated hardware can interpret them, and the same for the VGA display output.

I ended up implementing a much more sophisticated CPU than what's in the book, with various optimisations to take advantage of the way the "Hack" architecture works. Running on a 25MHz clock (and on actual hardware!), this is a lot faster than the simulators we were using back in the club days. The game of Pong that ships with the book is so fast that it's hard to see the ball (though I got very good at it after test-playing it for months). I remember that towards the end of the book, @h-lame had tried to write a Mandelbrot implementation but we found that the simulator was too slow to render it properly; if you still have the source code let me know because it would be really cool to try it out on real hardware.

At the same time, I was unhappy with the fact that in the book (spoiler alert), no one ever actually gets to play Tetris!! So I dusted off my knowledge of the "Jack" language and built the most full-featured version of Tetris I could fit within the punishingly low 32,768-instruction limit of the Hack architecture: https://github.com/leocassarani/Tetris.jack

Initially I was using the compiler, "VM translator" and assembler that we built in Ruby as part of the club, but I pretty quickly found that I needed tooling that could optimise my code to run faster and fit into a smaller binary if I wanted to compile large programs like Tetris with it. So naturally I had to write my own Jack optimising compiler in Rust, which encapsulates all the different stages that we wrote separately as part of the book (Jack to VM, VM to assembly, assembly to binary): https://github.com/leocassarani/jackc

Finally, when you're spending weeks working on a large project in Jack, it can get very frustrating to be editing these programs without help from your editor, so naturally I ended up writing a syntax highlighting plugin for Vim: https://github.com/leocassarani/jack.vim

-- Leo Cassarani, 13:24, Wednesday, 14th October 2020

• NAND to Tetris on the iCEBreaker FPGA
• The ultimate conclusion to NAND to Tetris
• A simple, end-to-end compiler for the Jack programming language
• Vim syntax highlighting for the Jack programming language