A. Tools and workflow

Two sets of tools meet in this book. The course has its own, which you use for labs, and the book uses a different set to check every example on the site. This appendix says which is which, what the book's tools do that you can repeat on your own computer, and what it leaves to the course's own tutorials.

The course's tools and the book's tools

The course uses Intel Quartus Prime to write, synthesize and program designs onto the DE1-SoC, and ModelSim to simulate them.^{F (fact ch01/tools)} Lecture 3 names ModelSim and Icarus Verilog as the digital logic simulators used for debugging Verilog.^{F (fact ch03/simulators)}

The book is checked with open-source tools, which can run unattended on any machine: the slang front end for syntax and style checks, Verilator as a second linter, Yosys to check that a module can be built as hardware and to count its storage, and Icarus Verilog to simulate. Every listing in the chapters is a file that these tools process, and every waveform and printed value comes from an Icarus run. The tools differ in what they accept, and Appendix C lists the differences that matter and what the book's code does about them.

The book's modules use only the constructs listed in Appendix C, but the book has not run them in Quartus or ModelSim. What differs between the two sets of tools is everything around the language: how a project is organized, how a simulation is started, how a waveform is viewed, and how the design reaches the board. For those, the course's tutorials and lab handouts are the authority, and this appendix does not reproduce them. The book has not run Quartus or ModelSim, so it does not describe their menus, windows or messages.

What the course's own material says about simulation

A few statements from the section slides are worth keeping in mind, because they explain behavior you will see in either simulator.

The section 3 slides say a test bench needs to end with $stop so that ModelSim pauses.^{F (fact ch03/modelsim-stop)} The same holds in Icarus, as the next section shows.

According to the section 3 slides, the course's ModelSim setup gives every piece of combinational logic a delay of zero.^{F (fact ch03/zero-delay-setup)} Icarus behaves the same way for the book's ordinary modules: a gate takes no time, and output changes appear in the same step as the input that caused them. Section 3.3 shows how the book adds gate delays, with separate simulation-only modules that never go into a design.

The section 3 slides show two ways to view waveforms, a ModelSim workflow and a workflow that writes a waveform file with a simulate-verilog command and opens it in the Surfer viewer.^{F (fact ch03/viewer-workflows)} The second route also writes a waveform file and opens it in a separate viewer, as the dump described below does, but it uses the course's own command and a different file format, .fst; the section on waveforms below covers the book's own route, which writes a VCD file.

In both waveform viewers the section 3 slides show, a menu on a signal (Radix in ModelSim, Format in Surfer) changes how its bits are displayed without changing the bits, and the common choices named are binary, unsigned, decimal (the slide's gloss: signed integer) and hexadecimal.^{F (fact ch03/radix-menu)} The section 3 slides warn that Surfer's default view of a partly driven 10-bit output reads all z, and that changing the signal's display base to binary shows the bits that are driven.^{F (fact ch03/surfer-zzz)} Section 3.2 works through the same trap.

Simulating with Icarus Verilog

Icarus works in two steps. iverilog compiles the design and the testbench into a file, and vvp runs that file. The commands below were run on the book's multiplexer and its testbench, which are the files mux2.sv and mux2_tb.sv of Section 3.1. Both files go on the command line. No top-level module was named, and the run still started from the testbench.

iverilog -g2012 -o mux2.vvp mux2.sv mux2_tb.sv
vvp -n mux2.vvp

The flag -g2012 selects the 2012 edition of the language, and the book's runner always passes it. The compile step printed nothing when it succeeded. The run ended at the testbench's $stop and printed one line that gives the line of the $stop, and the time at which it ran.

The flag -n makes $stop end the run. Without it, vvp treats $stop as a request to pause, prints a short banner and a prompt line instead of exiting. The book's runner always passes -n.

The time is printed in the simulator's time unit. With no timescale directive in the source, Icarus labeled the time with its default unit, which it printed as 1s; the book's runner passes a small file that sets a unit of ps, so its output says ps. The number is a count of simulator steps and says nothing about real speed (Appendix D).

Reading values with $display

A testbench that checks itself prints what it finds. This one tries every input of the multiplexer and compares the output with its own copy of the rule.

// A self-checking testbench for mux2: it compares y with its own model of the mux and counts the mismatches.
module mux2_selfcheck_tb();
  logic s, d0, d1, y;
  int errors;

  mux2 dut(.*);

  initial begin
    errors = 0;
    for (int i = 0; i < 8; i++) begin
      {s, d1, d0} = i[2:0]; #10;
      if (y !== (s ? d1 : d0)) begin
        errors++;
        $display("mismatch: s=%b d1=%b d0=%b y=%b", s, d1, d0, y);
      end
    end
    $display("DD errors=%0d", errors);
    $stop;
  end
endmodule

The same pair of commands runs it. The output below is from the book's runner, which passes -n and the unit file described above. The first line begins with DD, which is the book's own convention for a value the site reads back. In your own testbenches write any text you like.

DD errors=0
hdl/ch03/s01/mux2_selfcheck_tb.sv:18: $stop called at 80 (1ps)

Output of the simulation for mux2_selfcheck

Looking at a waveform

For a waveform, the testbench asks the simulator to record the signals in a file. Add two lines at the start of the testbench's initial block: $dumpfile("mux2.vcd"); names the file and $dumpvars(0, mux2_tb); records every signal in mux2_tb and, because of the 0, in every module inside it, such as dut.

Compile and run as before. The run then creates mux2.vcd, a text file in the VCD format that lists every change of every recorded signal with its time. Any waveform viewer that reads VCD files can open it; the book does not describe a particular one. This is a different route from the course's Surfer workflow above, which opens an .fst file written by simulate-verilog.

The book's own figures are made differently. The book's runner compiles in a small helper module that records the signals, reads the file, and draws the figure from the events it holds, so the figure shows exactly what the simulation did, and the shown testbench has no recording lines in it.

Checking a module for style and structure

Simulation shows what a module does on the inputs you tried. A linter looks at the code itself and can see problems that no test happens to trigger, such as the latch that a missing else creates. Verilator can be run on its own:

verilator --lint-only -Wall latch_demo.sv

On the module with the missing else from Appendix C, this printed a %Warning-LATCH line naming the signal and the line of the always_comb, and the command exited with a failure status. On a module without the problem it printed a short Verilator report and exited with status 0. Appendix C lists which of the four tools notice which mistakes; no single tool notices all of them.

The course's workflow, as its own material states it

The steps below are what the section slides and lab handouts say. The book has not run them, and it states only what those sources state; for everything else, use the course's tutorials. Each statement is a registered fact with its source.

Simulating with ModelSim. The section 3 slides give this ModelSim workflow: double-click Launch_ModelSim.bat in the project directory; edit runlab.do to add the files to compile (modules and test benches), to name the test bench to simulate and to name the waveform script file (*_wave.do), which does not exist at first; run do runlab.do in the Transcript pane; add signals to the Wave pane by dragging them there from the Objects pane; and with the Wave pane selected press Ctrl+S to overwrite the waveform script file.^{F (fact apA/modelsim-script-workflow)} Lab 1 says a project can have several .do files for different simulations (its examples are runlab_mux4.do and runlab_lab1.do) so that you can switch between simulations without editing files.^{F (fact apA/modelsim-do-files)}

Viewing with Surfer. The section 3 slides give this Surfer workflow: create a <module_name>_tb.fst file with the course's simulate-verilog command, naming the test bench module and then listing the files to compile (both modules and test benches); run scp to copy the file to the wanted directory (the command that simulate-verilog prints can be copied and pasted); view the waveforms in Surfer; and save the waveform state with files > save state as...^{F (fact apA/surfer-route)}

Quartus projects. Lab 1 says Quartus Prime is preloaded on the lab machines and can be installed on your own computer by following the course's Software Setup page, and it tells students to complete Sections 0 through 8 of the lab manual's Quartus tutorial (a Windows version and a MacOS/Attu version), taking notes because the steps repeat in later labs.^{F (fact apA/quartus-tutorial)} Lab 2 says to copy the earlier lab's project folder into a new project folder, to add the new .sv file to the Quartus project and to set that file as the top-level module.^{F (fact apA/quartus-add-top)} Lab 4 says to create a new directory for the lab, separate from the other lab folders, to put the downloaded starter project files in it, and to start a new project there whose top-level module has the name the lab gives.^{F (fact apA/quartus-new-project)}

Loading the board. Lab 1 says that to move from one design to another you close the Quartus project that is open, open the other project, open the file ProgramTheDE1_SoC.cdf and then send the design to the DE1-SoC; it also says to synthesize the bit files ahead of time, because that can take five minutes or more for later projects.^{F (fact apA/programmer-step)}

What this appendix leaves to the course

Everything else about setting up a Quartus project, the steps from a design to a programming file, loading a design onto the board, and starting a ModelSim simulation is part of the course's own tutorials and lab handouts. Follow those exactly: the course staff can help with them and the book cannot. The board itself, its switches, keys, lights and displays, is a separate reference, which the book will give in a later appendix.