README.md

# GTI VHDL Crash-Course

This is a small [VHDL](https://en.wikipedia.org/wiki/VHDL) Crash-Course I use for teaching in the Module "Grundlagen der Technischen Informatik" (GTI) at FAU. This Repository contains all tasks solved in the Exercises in form of templates students can fill out on their own as well as solutions. This Project also comes with [Testbenches](https://vhdlwhiz.com/terminology/Testbench/) for all tasks with which you can test the solutions as well as your own implementations.

* [Getting Started](#getting-started)
  * [GHDL](#ghdl)
    * [Windows/Mac](#windows/mac)
    * [Linux](#linux)
  * [GTKWave](#gtkwave)
    * [Windows](#windows)
    * [Mac](#mac)
    * [Linux](#linux)
* [Usage](#general-description)
  * [Usage: GHDL](#usage:-ghdl)
  * [Usage: GTKWave](#usage:-gtkwave)
* [VHDL References](#vhdl-references)
* [Bonus: Makefile](#bonus-makefile)
* [Bonus: Additional Task](#bonus-additional-task)
* [Problem Reporting](#problem-reporting)

## Getting Started

**If you work directly on a CIP \[RECOMMENDED\], you can skip this section** 

The following section will go through how you can install a simulator as well as a wave viewer in order to test your written VHDL-Code. This tutorial will focus on [GHDL](https://github.com/ghdl/ghdl) as the Simulator being used as well as on [GTKWave](https://gtkwave.sourceforge.net/) as the wave viewer. Fell free to use other Simulators/Wave Viewer like [Xilinx Vivado](https://www.xilinx.com/products/design-tools/vivado.html) or [ModelSim](https://eda.sw.siemens.com/en-US/ic/modelsim/), but your simulator needs to support VHDL-2008, otherwise some code wouldn't be able to run. 

The following guide will focus on the previous mentioned Open-Source-Software alternatives.

### GHDL

First we want to install GHDL as our main simulator. For that, head over to https://github.com/ghdl/ghdl/releases/latest and download the latest release for the OS of your choice.

#### Windows/Mac

For Windows and Mac the install should be straight forward. Download the respective release and put the program inside a suitable directory (e.g. the Programs folder). After that you need to add the "bin"-folder of the release to your PATH-Variable. For this you can follow [this guide](https://medium.com/@jamexkarix583/add-bin-folder-to-the-path-772de253f579). After that you should be able to use the "ghdl" command in your terminal.

```
$ ghdl version
GHDL 3.0.0 (3.0.0.r0.g7de967c51) [Dunoon edition]
 Compiled with GNAT Version: 7.5.0
 mcode code generator
Written by Tristan Gingold.

Copyright (C) 2003 - 2023 Tristan Gingold.
GHDL is free software, covered by the GNU General Public License.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
```

#### Linux

The Linux install can be a bit tricky depending on your distribution. For this I can't really give a straight forward way of installing it, but I would advise you to check your packet managers. If GHDL is not provided in your standard packet managers, try others like SNAP. (I personally use the SNAP build on my [Manjaro](https://manjaro.org/) machine).



### GTKWave

Now that we have our Simulator up-and-running we head over to our wave viewer so that we can view our signals produced by our architecture.

#### Windows

For Windows head over to the download [here](https://sourceforge.net/projects/gtkwave/files/gtkwave-3.3.100-bin-win32/gtkwave-3.3.100-bin-win32.zip/download) and run it.

#### Mac

Unfortunately I don't have a device to test the installation. There are a few packet-managers that seem to have builds of GTK-Wave, like [Homebrew](https://brew.sh/) or [MacPorts](https://www.macports.org/), but I haven't tested those.

#### Linux

GTKWave most of the time ships with your favorite packet-manager. If you are not able to find it, you can download it manually over the download [here](https://gtkwave.sourceforge.net/gtkwave-3.3.117.tar.gz) and build it yourself.

## Usage

Now that we have our software up-and-running we can continue with actually using the software. First I will go over how to simulate your VHDL-Code via GHDL and after that I will show you how you can view your own wave diagrams via GTKWave. 

**[Important: Every cmd should be run from the project-root, otherwise it could be difficult to get it to run]**

### Usage: GHDL

"Compiling" a VHDL simulation can mainly be divided into three separate steps. The first step ist to analyze your VHDL file as well as your Testbench you want to use to check if any syntactical errors are still present in your files. For that type the following command into your terminal of choice:
```
$ ghdl -a --ieee=synopsys --std='08' <source_file.vhd> <tb_source_file.vhd>
```
The *std*-Flag is necessary for the provided Testbenches and source-files to compile because especially the Testbenches are using features only presented in the VHDL-2008-Standard or higher. The *ieee*-Flag won't be necessary for running the Testbenches provided in this repository but are crucial for the VHDL-Files used in the Labs.

After that you need to elaborate your design unit (meaning your Testbench you want to run in the end) and check if any errors are still present in your unit. This shouldn't result in problems in this project though because the Testbenches should (hopefully) work. For this run the following command:
```
$ ghdl -e --ieee=synopsys --std='08' <tb_source_file>
```
Notice this time you don't specify the file extension, because you just tell the simulator to run the Testbench you analyzed earlier. It will use the newly generated ".cf" file, so you don't have to navigate into the "sim"-folder for this. You also need the "std"-flag from the command earlier, otherwise it will probably not work.

Last but not least you can finally run your simulation. For that type in following command:
```
$ ghdl -r --ieee=synopsys --std='08' <tb_source_file> --wave=<tb_source_file.ghw> --stop-time=<amount-of-time>
```
Here we have two additional flags. The *wave*-Flag specifies how the resulting wave diagram needs to be named which we can later use in GTKWave in order to view our signals. The *stop-time*-Flag just indicates for how many seconds the simulation needs to compute it's signals. *25sec* as an parameter should plenty enough for all simulations.

The following picture shows an example on how to run an Testbench by manually typing out the commands: <br/>
(Note: if you want to run your own implementation, replace the "src" with "template")

<p float="left">
  <img src="doc/images/ghdl-usage.png" width="1000" />
</p>

If you are using a Linux system (e.g. the CIP) you don't have to manually type these commands by hand. Just type
```
$ make solutions
```
if you want to run the simulations and get the waveform diagrams (located in the "wav"-folder) for the solutions and
```
$ make templates
```
if you want to run the simulations and get the waveform diagrams for the your own solutions (have to be located in the "templates"-folder).

If you only want to simulate a specific architecture you designed and not all of them at once, use these commands depending on the simulation you want to run instead.
```
$ make counter_temp
$ make or_reduce_temp
$ make alu_temp
$ make watch_temp
$ make simulation_temp
```

### Usage: GTKWave

Now that we have our *.ghw*-File we can use it for usage in GTKWave. This example uses the *tb_or_reduce.ghw* wave diagram you get when running the simulation for the *or_reduce* architecture and Testbench, but this also works for all other VHDL-tasks. For this I would also like to advise to have a look on the official user guide of GTKWave found [here](https://gtkwave.sourceforge.net/gtkwave.pdf).

First start up GTKWave and load wave diagram file as seen in the screenshot below.

<p float="left">
  <img src="doc/images/pic1.png" width="500" />
  <img src="doc/images/pic1-2.png" width="500" /> 
</p>

After that you should your components structured in a hierarchal way in the "SST"-Tab. You can click on your components and select your signals you want to use from the "Signals"-Tab, as shown in the next picture.

<p float="center">
  <img src="doc/images/pic2.png" width="700" />
</p>

If you want to automatically zoom in/out so that you can see the entire simulation, click the "Zoom-fit" button on the top. 

<p float="center">
  <img src="doc/images/pic3.png" width="700" />
</p>

Last but not least you can change the data-types of your signals. Just right-click on them, select the option "Data Format" and select the type you need.

<p float="center">
  <img src="doc/images/pic4.png" width="700" />
</p>

## VHDL References

There are multiple good resources on VHDL out there, so these are just a few I personally love to use and often come back to when writing VHDL-Code:

* [Nice, straight forward cookbook for VHDL](https://www.ics.uci.edu/~jmoorkan/vhdlref/)
* [Collection of different VHDL Tutorials and Examples](https://nandland.com/learn-vhdl/)
* [Good explanations of different terminology](https://vhdlwhiz.com/terminology/)

If you have more useful resources, let me know through a Mail (s. [here](#problem-reporting)).

## Bonus: Makefile

The Project also contains a Makefile that you can use for compiling and running the Testbenches provided to you for Exercise 2 of the second Lab. You can find it in the *makefile*-folder. Just put it into the root of *alarm_clock* project.

You can compile the individual VHDL-Files with the following commands:
```
$ make int2ascii
$ make counter
```

## Bonus: Additional Task

The project also has a completely new task I came up with myself. If you want to have an exercise which combines all the things we learned about VHDL in one little code example, this task is for you.
```
Given an entity "counter" representing an syncronous 4-Bit counter 
with an asyncronous Reset-Signal and with and direction signal 
indicating if the counter should count up- or downwards, design two different
architectures. One should be the implementation of an simple binary counter
and the other of a more challenging gray-code counter. 
For both of these counters you mustn't use a Look-Up-Table but rather use
the built in functionalities of the types you are given as well as the
functions already provided by the template.

The template for this project can be found in the "templates"-folder, 
the solution in the "src"-folder.

For testing your implementation you can use the "tb_counter.vhd" Testbench
inside the "sim"-folder (or just run 'make counter_temp') and then run the 
newly created wave-file with GTKWave and see if it behaves as expected.
```


## Problem Reporting

If you find any issues or any bugs in this project you would help me out a ton by reaching out to me with them. For this you can either create an Issue directly on GitLab or you can just contact me over my E-Mail maxim.balajan@fau.de

Thanks a ton and I hope this little projects helps you with understanding the base concepts of hardware design taught to you in GTI :)