search

jopdorp / nand2tetris-verilog

MIT License
19 stars 7 forks source link

readme

Nand2Tetris Verilog

What is this about?

Nand2Tetris is an awesome course where you learn how to build a computer.
You build the all chips and architecture from the ground up, in a simplified HDL language.
After this, you create an assembler language, an operating system called Jack OS.
Then a virtual machine and a java-like language called Jack.

Why this repo?

This is a SystemVerilog version of the course materials on hardware design.
The purpose is usage by other students, so go ahead, give it a try!
The course Nand2Tetris is on coursera https://www.coursera.org/learn/build-a-computer There is also a website https://www.nand2tetris.org/
I can also highly recommend the book from the course:

The Elements of Computing Systems
Building a Modern Computer from First Principles

This project is an implementation of the HACK architecture in SysytemVerilog.
The there is a branch per week, with the solutions of previous weeks but not the current one. Use this to implement the architecture yourself every week.
For each chip, there is a testbench to test its functionctionality.

Installation

So, you want to try to build hack in SystemVerilog!

The first step is cloning thin repo, so open up your favorite terminal and type:

$ git clone https://github.com/jopdorp/nand2tetris-verilog.git

I recommend using git, but if you don't want to use git, you can download this repository as a zip file!
https://bitbucket.org/jopdorp/nand2tetris-verilog/downloads/

Requirements

Python:

If you don't already have python installed, you can install it as follows:

In Ubuntu you can do something like:

$ sudo apt install python3.6

More info: https://docs.python-guide.org/starting/install3/linux/

In Windows you usually would download the installer from https://www.python.org/downloads/windows/

Mac OS X:

$ brew install python

Python libraries

When you have python installed, you can:

$ cd nand2tetris-verilog
$ pip install -r requirements.txt

Iverilog:

At the time this was writte, you need to buuld iverilog yourself beause we need new functionality which has not yet been released in a stable release. For windows you will first need to install Msys2 64 bit which can be found here:

for ubuntu install the prerequesites like this:

$ sudo apt install flex bison gperf

then clone and build iverilog

$ git clone https://github.com/steveicarus/iverilog.git
$ cd iverilog
$ git checkout v11_0
$ sh autoconf.sh
$ ./configure
$ make
$ make install

Verilator:

When you have implemented all chips, you can test the computer with verilator. It will open a window and poll your keyboard, which are integrated with the provided screen chip and the keyboard register in the computer chip template.

Linux:

$ sudo apt-get install -y verilator

Mac OS X:

$ brew install verilator

Windows: Open Msys2 64 bit

$ pacman -S mingw-w64-x86_64-verilator

A note about editors

I recommend using VSCode from microsoft, which has as nice system verilog plugin which it will suggest to install when you open a .sv file.

If you don't want a big program like that, there are other options:

There should also be plugins for vim and sublime text, but don't know the details about those.

You're ready!

Usage

If you use windows, always yous your MSYS2 64 bit terminal.

The testbenches can be run using "test.py".

  1. It compiles all verilog files in the project
  2. It runs the test benches, by default all files that end with "_tb.sv" in the project

To verify that your environment is up and running type:

$ python test.py 00

You should see the following output:

Starting compilation of project 00...
iverilog -grelative-include -g2012 -o ./build/hello_verilog_tb.sv.vvp /c/dev/nand2tetris-verilog/00/hello_verilog_tb.sv
Finished compiling!

Starting tests in project 00
Hello world!

Found 0 assertion errors in hello_verilog_tb.sv.vvp

Finished testing:

From a total of 1 test benches.

1 test benches ran without any runtime errors

All tests succeeded!

Note that there is # Hello world! before the script quits the simulator.
If there are not errors and you see this message, it means everything is good to go!
It could be that you'll see some error, please see the Troubleshoot section

Now you can implement your first chip.
I advise to start with not_n2t.sv, you can test it as follows: 

$ python test.py 01 not_n2t_tb.sv

This should give you an assertion error:

Starting compilation of project 01...
iverilog -grelative-include -g2012 -o ./build/not_n2t_tb.sv.vvp /c/dev/newnand/nand2tetris-verilog/01/not_n2t_tb.sv
Finished compiling!

Starting tests in project 01
not_n2t_tb.sv.vvp
ERROR: C:/dev/newnand/nand2tetris-verilog/01/not_n2t_tb.sv:12: assertion fail! in 0 out z, expected: 1
       Time: 1 Scope: not_n2t_tb.assert_else_error
ERROR: C:/dev/newnand/nand2tetris-verilog/01/not_n2t_tb.sv:12: assertion fail! in 1 out z, expected: 0
       Time: 3 Scope: not_n2t_tb.assert_else_error

Found 2 assertion errors in not_n2t_tb.sv.vvp

Finished testing:

From a total of 1 test benches.

0 test benches ran without any runtime errors

1 test benches had errors, of which:
1 ran, but had a total of 2 assertion errors

Implement the chip and rerun the test to see if it works!
When you chip is correctly implemented you should see the following:

$ python test.py 01 not_n2t_tb.sv

Starting compilation of project 01...
iverilog -grelative-include -g2012 -o ./build/not_n2t_tb.sv.vvp /c/dev/newnand/nand2tetris-verilog/01/not_n2t_tb.sv
Finished compiling!

Starting tests in project 01
not_n2t_tb.sv.vvp

Found 0 assertion errors in not_n2t_tb.sv.vvp

Finished testing:

From a total of 1 test benches.

1 test benches ran without any runtime errors

All tests succeeded!

Thanks

Cool links

Verilog learning material: