Modelsim Project Setup
Last Update: 2023-10-28
This tutorial will be using the verilog files available here:
Verilog Files
When you first open Modelsim, there might be a welcome window. Press "Jumpstart" to close.
With that closed, you should be greeted with the project startup page. This shows a list of the various libraries that are loaded.
To get started with a new project, we first need to set our working directory. Go to File > Change Directory... and navigate to a directory where you want to perform your simulation. I typically create a "sim" directory within my projects specially for this purpose.
With the working directory set, we can create a new project. Navigate to File > New > Project. You need to choose a project name. For this tutorial, I am going to call this "counter-test" The other fields in the window include the project location (which should be the directory you just chose) and the library name (which is where the compiler will place all the compiled modules).
Once you have named the project, press OK. A new window should pop up. Click on "Add Existing File". In the following pop up, click "Browse" and navigate to your verilog files. Select all that you need for the testing. There are two options for adding the files. The default is to reference the HDL source from its curernt location. This allows you to keep your code in one location but you must not move it later (or you'll have to re-reference it in Modelsim). The second option is to copy it to the project directory, which I usually do not recommend since you will then have two copies of your source files and you will need to keep them in sync. When you are done, press OK and close the remaining pop up windows.
In the main window, you should see your source files appear. Next to each will be a blue questionmark. This indicates that Modelsim has not yet tried to compile the source files.
To fix this, you have two options. First option is to compile each one at a time by right-clicking on the file and selecting Compile > Compile Selected.
The second option is to navigate to the window menu and select Compile > Compile All.
If everything went well, you should have no errors in the transcript window and the files will have a green checkmark:
If things went less then well, you can navigate to Compile > Compile Summary to view the compiler errors.
> Running a Simulation
Once all your source files compile successfully, navigate to Simulate > Start Simulation.
This will open a window where you can select the library module that you want to run as the top level in your simulaton. Click on the '+' icon next to your library name (most likely, "work") and select the module to test.
Select "OK" and the simulation view will be opened. To the left is the hierarchical display of all the instantiated modules in your design. When one is selected, the blue "Objects" window will show the relevant variables, nets, and parameters along with their current values.
For a simple test bench like the one we are using, the waveform viewer is a good way to get an idea of what the circuit is doing. The first step to using the waveform viewer is to add a signal to view. This can be done by right clicking on the instance of interest from the design hierarchy and selcting Add to > Wave > All items in region.
A wave viewer window will appear. A few key buttons to note:
- Run: this runs the simulation for the currently selected run time.
- Break: this halts the simulation in case it is taking a long time or you accidentally create an infinite combnatorial loop.
- Zoom: allows you to zoom (very useful)
For the simple counter test, we can set the run time to 100 ns and press the Run button. After pressing (F) to soom full, we see that we get a nice clock signal but the counter's value is this flat red line. In Modelsim, a red line means that the signal contains at least one bit with value 'X', which is "unknown." This happens since we did not initialize the counter's internal register to some known value at the beginning of the sim. (You can tell most simulators to do this initialization automatically, typically with all 0's or random data, if you so choose).
For the sake of the tutorial, we will try setting its value in the sim instead of using a reset or initial block. To do this, go back to the simulation window and right click on the counter's internal register and select Modify > Change Value.
This will open a window that allows you to set the value of the signal. In this case, I am going to set the counter to all zeros.
If we go back to the wave window and press the Run button, we see that our counter starts to work as expected!
> Tips
Saving your waveform window setup
Let's say that you are looking at a design with a few hundred signals in the wave viewer and you have spend a few hours getting them all arranged nicely in just the right order. You suddenly notice that your laptop's battery is at 5% and you'll need stop working ASAP. The good news is that you don't have to lose all that organizational work! Simply press Ctrl+S in the waveform window (File > Save Format) and your configuration will be saved. The next time that your open the wave viewer, this config can be loaded with File > Load and selecting the ".do" file.
Keyboard "shortcuts"
Many of the commands that you run via the GUI menus can be run from the sim window's transcript prompt. Take for example the 'run' command. Once your design is loaded, you can type "run" to start the simulation. 'restart' will also reset the simulation.
Opening an existing project
To open an existing project, follow the directions to change the directory as outlined above. Then navigate to File > Open, set the file type to Project Files (*.mpf) and locate the project file you want to open.
With that closed, you should be greeted with the project startup page. This shows a list of the various libraries that are loaded.
To get started with a new project, we first need to set our working directory. Go to File > Change Directory... and navigate to a directory where you want to perform your simulation. I typically create a "sim" directory within my projects specially for this purpose.
With the working directory set, we can create a new project. Navigate to File > New > Project. You need to choose a project name. For this tutorial, I am going to call this "counter-test" The other fields in the window include the project location (which should be the directory you just chose) and the library name (which is where the compiler will place all the compiled modules).
Once you have named the project, press OK. A new window should pop up. Click on "Add Existing File". In the following pop up, click "Browse" and navigate to your verilog files. Select all that you need for the testing. There are two options for adding the files. The default is to reference the HDL source from its curernt location. This allows you to keep your code in one location but you must not move it later (or you'll have to re-reference it in Modelsim). The second option is to copy it to the project directory, which I usually do not recommend since you will then have two copies of your source files and you will need to keep them in sync. When you are done, press OK and close the remaining pop up windows.
In the main window, you should see your source files appear. Next to each will be a blue questionmark. This indicates that Modelsim has not yet tried to compile the source files.
To fix this, you have two options. First option is to compile each one at a time by right-clicking on the file and selecting Compile > Compile Selected.
The second option is to navigate to the window menu and select Compile > Compile All.
If everything went well, you should have no errors in the transcript window and the files will have a green checkmark:
If things went less then well, you can navigate to Compile > Compile Summary to view the compiler errors.
This will open a window where you can select the library module that you want to run as the top level in your simulaton. Click on the '+' icon next to your library name (most likely, "work") and select the module to test.
Select "OK" and the simulation view will be opened. To the left is the hierarchical display of all the instantiated modules in your design. When one is selected, the blue "Objects" window will show the relevant variables, nets, and parameters along with their current values.
For a simple test bench like the one we are using, the waveform viewer is a good way to get an idea of what the circuit is doing. The first step to using the waveform viewer is to add a signal to view. This can be done by right clicking on the instance of interest from the design hierarchy and selcting Add to > Wave > All items in region.
A wave viewer window will appear. A few key buttons to note:
For the simple counter test, we can set the run time to 100 ns and press the Run button. After pressing (F) to soom full, we see that we get a nice clock signal but the counter's value is this flat red line. In Modelsim, a red line means that the signal contains at least one bit with value 'X', which is "unknown." This happens since we did not initialize the counter's internal register to some known value at the beginning of the sim. (You can tell most simulators to do this initialization automatically, typically with all 0's or random data, if you so choose).
For the sake of the tutorial, we will try setting its value in the sim instead of using a reset or initial block. To do this, go back to the simulation window and right click on the counter's internal register and select Modify > Change Value.
This will open a window that allows you to set the value of the signal. In this case, I am going to set the counter to all zeros.
If we go back to the wave window and press the Run button, we see that our counter starts to work as expected!
