Digital Computers 1

Digital Computers 1

1. Repository description

This project aims to provide a fully open-source alternative to the Open CourseWare Digital Computers 1 Laboratories taught at Politehnica University of Bucharest, during the second semester of the university year 2020-2021.

The official guideline recommends using either the Xilinx ISE or Vivado. Since, both of them are memory heavy (tens of Gb) and closed-source, this repository was born in order to prove a change is possible.

Here is the list of the improvements I brought:

Makefile with Icarus Simulator support (though working, might still be improved)
Verilator for linting with all warnings solved
Correct use of both nonblocking and blocking assignments
- Wrote an systemized explication about the differences between the two
Coding style (as best as I could)
Improved checkers (e.g. lab-06)
Removed unsynthesizable initial blocks
Provided information about open-source tools
Synthesis script (only for some laboratories)

For more information or a syllabus check out the course description page here.

I encourage you to watch the online lectures here. This course was taught by Dan-Ștefan Tudose.

2. Requirements

I do recommend you do read the following tutorial first: Running Verilog code on Linux/Mac.

2.1. Simulation and Synthesis

This project uses Icarus Verilog for compiling and simulation. Do note that it was tested only on a Linux platform with Make support. Viewing waveforms can be done with any program that reads .vcd files.

If you would also like to synthesize some of the codes, the only tool I found was Yosys. For rendering the generated schematics you'll need xdot for the .dot files. An alternative is to render the .json connection description with netlistsvg. I recommend you use the netlistsvg demo online without installing it. (Note: The first example picture in this README was produced by netlistsvg.)

If you are using a Debian-based system, run the following command to install the mentioned packages:

# for building and simulation + waveform viewing
sudo apt install make iverilog gtkwave

# optional, used only for synthesis
# note: depends on xdot
sudo apt install yosys

2.2. Integrated Development Environment

If you are interested in a IDE, I would recommend VSCodium. Install the Verilog-HDL support for VS Code extension (see future note). If you are a beginner, the Verilator linter will provide more educational warnings.

sudo apt install verilator

Go to the extensions settings in VSCodium and configure it like this:

# Verilog › Linting: Linter
verilator

# Verilog › Linting › Verilator: Arguments
-Wall -Wno-STMTDLY -Wno-ASSIGNDLY --bbox-unsup --bbox-sys

Note: If you took my advice and installed VSCodium, you'll need to enable the VSCode Marketplace using these instructions.

If you are interested in a open-source auto-formatter them I found this Sublime System Verilog plugin. Just place your cursor on the endmodule keyword, press Ctrl + Shift + P and type Alignment. I will note that before this I usually run this command:

for i in *.v; do
    expand -t 4 "$i" | tr -s " " > tmp
    cp tmp $i
done
rm tmp

3. Usage

Open the directory corresponding to the laboratory you want to test. Run make build for compiling, make run for simulation, and gtkwave waves.vcd for viewing the resulting waveforms.

Some laboratories, like lab-05, include a synthesis script. If you run make synthesis in the respective folder, both a .dot and .json file will be generated both containing a logic gate schematic circuit based on the Verilog code. The .dot is opened and rendered by default when running the script. I shall warn you that the .json schematic description contains multiple module implementations, so when using netlistsvg just delete from the .json file the unnecessary ones.

4. Other projects

A follow-up to this repository is Digital Computers 2. Like this repository, it aims to provide a fully open-source alternative to the Open CourseWare Digital Computers 2 Laboratories (PUB).

During courses we were taught Malvino and Brown's SAP-1 computer architecture. A very comprehensive repository implementing this architecture can be found here: https://github.com/EnigmaCurry/SAP.

If you are interested in making a Printed Circuit Board out of Verilog code, check out: http://pepijndevos.nl/2019/07/18/vhdl-to-pcb.html.

4.1. Linux on Litex

During the 2021 summer I worked along with my teaching assistant, Ștefan-Dan Ciocîrlan, on running Linux on Litex on a Arty A7-100T development board. I used Symbiflow as an open-source alternative to Vivado.

A working project, but old, project can be found on the examples repository.

Following a more modern project, Linux on LiteX with a 64-bit RocketChip CPU, I tried to compiled the Verilog code for a Rocket CPU implementation, but ran out of memory since it used more than 120GB of RAM.

Following a lighter project, Linux-on-LiteX-VexRiscv, I got Litex up and running flawlessly, but could not manage to run Linux without errors.

5. Acknowledgments

I would like to thank again Ștefan-Dan Ciocîrlan for all his support, this repository would not be possible without him.

Although, they did not contribute directly to making this project, I would like to thank the following people for their emotional support:

mateibarbu19/digital-computers-1