CS 232: Lab 1

Lab 1: Digital Logic CAD Tools

The purpose of this lab is to familiarize you with logic gates and basic digital logic design techniques. We will be using a digital logic CAD program, Quartus, to generate our designs using a graphic layout tool. We will use a simulation tool, ghdl, to test our designs and ensure they are working correctly. We will download the program to an FPGA board to see it in action, which is what I hope you will do for most projects. But if that isn't possible (we do have a limited number of boards), you can create an animation of your simulation. We will practice making that animation as well.

If you want to watch a movie of the first 40 minutes of the lab Zoom session from Fall 2020, please do so here.

Design a Circuit using Quartus

1. Log into the lab computer (it is called a "dwarf" because it is named after one of the dwarves in the Lord of the Rings).

   + (If you are using your laptop)

   If you are not in the lab, you will need to log into the computer remotely. You will need to do so using your Terminal (or equivalent if on a Windows machine). You will be running all programs from the terminal and you will have access to the GUI on the applications we us (Quartus, GTKWave, and Python), but it will be slow and you will not be looking at the desktop of the lab computer.

   1. If you are on a Mac
      1. If you do not have XQuartz installed, then you will need to install it (this is the application that runs on your computer but allow the remote computer to pop up windows).
      2. Open a Terminal on your laptop. Note: this may need to be an XQuartz terminal, rather than a Mac terminal. Try the Mac Terminal first, and use it if you the display works correctly (I.e. if you are able to see Quartus run when you get to that task in a few steps).
      3. Open a secure remote connection to on of the lab computers. You can choose from fili, kili, ori, nori, dori, bofur, and bombur. You will need to include your username and a flag indicating that you want to allow graphic information to be sent to your laptop (-Y or -X, and if you have a slow connection, -Y is a better choice). If I am logging into fili, then this is the command I use
         ssh -Y srtaylor@fili.cs.colby.edu
         You need to use your username instead of srtaylor and you choose one of the computers and add .cs.colby.edu after its name.
   2. If you are on a Windows machine
      1. You may want to watch this video, that a student found to be helpful.
      2. Install XMing and Putty
      3. Start XMing
      4. Start Putty, but you need to adjust your settings: Find the SSH settings, and click on the X11 settings, select "Enable X11 forwarding" and enter "localhost:0" as the host. You might want to save these settings. You also need to enter the name of the host computer. Choose one of the dwarves (fili, kili, ori, nori, dori, bofur, or bombur) and provide the name with .cs.colby.edu after it, e.g. fili.cs.colby.edu.
      5. Press the connect button (Sorry, Stephanie doesn't remember exactly what it says on it!)
   3. Enter your password, and you should see the prompt change from your usual prompt to one indicating which computer you are on. For example, when I log into fili, here is what I see
      fili:~>
      
   4. Now you can follow all the instructions for students in the lab, because anything you type after that prompt is commanding a lab computer to do something.

   Quartus is the main application we are doing to use to desing our circuits. Early in the semester, we will be drawing circuit graphically by pictures of gates with pictures of wires. Then, we will switch to programming in a language called VHDL.

   We start Quartus from the command line of a terminal, so if you are in the lab, open a terminal. If you are not in the lab, then open a terminal on your laptop and ssh in to one of the lab computers by following the instructions above.

   When we start an application from the command line, we can't use that shell again until the application is closed, unless we start it in the background. We can run any program in the background by putting an ampersand after the command. To run Quartus in the background, we type

   quartus &

   The first time you open Quartus, it will prompt you to pay for the full version. Instead, indicate you want to use the web version.

   

   Quartus should start up. In the main window are buttons to open an existing project (Open Project) and to create a new project (New Project Wizard). Press the New Project Wizard button.

   

   Specify where you want to put the project and a name for it and the top level design entity. As noted, the project name and entity name must be identical. You should put each project in its own sub-directory, probably inside a cs232 folder.

   

   We have no design files to add, so skip the next screen.

   You will be testing the circuits in one or two ways - you will simulate the circuit, and, if you are in the lab and all is working, you will also be able to run the circuit on the FPGA board. Today, my plan is for everyone to test on the boards, but this is the first time we are using the new boards, so I expect something will go wrong and we will need to adapt. Select the device for the DE0 board, which is a Cyclone III FPGA with the name EP3C16F484C6. You should use the Family list to choose Cyclone III, then you can either scroll through the Available devices list until you find it, or you can copy-paste the name into the Name filter. You will probably need to use Control or right-click instead of Cmd. Once you have the right device name in the list, select it (it will appear blue as shown in the image below).

   

   That should complete your project setup.

   After creating the project, select File::New and pick a Block Diagram/Schematic File.

   

   In the block diagram file you can now lay out circuits graphically and connect them with virtual wires.

2. Using the graphic layout tool, make a simple combinational logic tree for the function F = AB + A'B'. Double-click on the dotted background or press the button above that looks like an AND gate to place a new module. There are many types of modules. We want to use a simple primitive logic gate, as shown below.

   

   Lay out two 2-input AND gates and one 2-input OR gate to build the circuit. Then connect the output of each AND gate to the inputs on the OR gate. You can click and drag to make wires.

   

   Create two input pins and one output pin, again by double-clicking and then selecting input or output from the pins category. Place the pins in the upper left (inputs) and upper right (outputs) of your graphical design. Then edit the names so the pins are named A, B, and F.

   Next, make a small wire coming out of each input pin and a small wire coming into the output pin. A really helpful feature of Quartus is that is allows yout to label wires. This makes virtual connections, so you don't need to have lots of crossing lines. To label a wire, simply type while it is selected. Label these as A, B, and F, respectively.

   Next, add two NOT gates in front of the second AND gate and feed the A and B inputs to the NOT gates. The final circuit is shown below.

   

   Select File->Save Project and save your work as a bdf file. Since it is the top level file in your project, give it the same name as your project name, in this case circuit1.bdf.

Model a Circuit Using GHDL

Our next goal is to simulate the circuit. First, we convert the circuit diagram to VHDL file. VHDL is a programming language designed for simulating circuits, and you will learn it in coming weeks. Then, we use the ghdl command line tool to run the simulation.

1. Select File::Create/Update::Create HDL Design File from Curent File.

In the popup, select VHDL and click Ok. This should create a vhdl file version of your circuit. The name of the file will end in .vhd

2. Now you need to create a driver file that sends signals into your circuit and accepts the output. An example for the circuit above is testbench.vhd. This file defines three signals: A, B, and F. It then assigns values to A and B at certain time intervals. These values and time intervals form the four possible combinations of A and B. The file then attaches these signals to the circuit you created above. Note that you will need to edit the testbench.vhd file so the component statement label matches the name of the circuit you created. I named mine test, so my version needs to say "component test" in the declaration section and "test port map" in the code section. If your file is named circuit1, then your file needs to say "component circuit1" in the declaration section and "circuit1 port map" in the code section.
3. Save your VHDL test bench file in the same directory with your circuit's vhdl file.

Note: If you are in Davis 122, the computers (i.e. the dwarves) have issues with file permissions. You probably won't be able to right-click and save. Instead, use one of these work-arounds:

1. Follow the link to the file, select is all, copy it, then create a new file in Quartus, paste into it, then save it.
2. Take advantage of the fact that your home directory on the dwarf can be mounted onto your laptop. Everyone at Colby has a "personal" directory that is stored on a file-server called filer.
   • If you are on a Mac, then go to the Finder, and under the "Go" menu select "Connect to Server" (or press Cmd-K), then type in smb://filer.colby.edu/Personal/srtaylor, but replace srtaylor with your Colby username. You can check out a video here.
   • If you are on a Windows machine, try typing \\filer.colby.edu\Personal\srtaylor into the path bar of Files Explorer.) It should open up a new window with access to the same files as you can see on the dwarf.

You should now be able download files onto the dwarf using your laptop. Just interact with the folder as if it is on your laptop.

4. In the terminal window on the dwarf, run the ghdl tool to compile the code, produce a simulation output (a .vcd file), and then view each signal over time with gktwave.

   The instructions are in this movie and below:

   1. Run the ghdl tool in the Terminal (making sure you are in the same directory as the .vhd files) to compile and simulate your circuit. Remember, I called my circuit circuit1, so my vhdl file is called circuit1.vhd.

      ghdl -a circuit1.vhd testbench.vhd
      ghdl -e testbench
      ghdl -r testbench --vcd=testbench.vcd
      

   2. Finally, open up the .vcd file in gtkwave.

      gtkwave testbench.vcd

      Once the window opens, select all of your signals and select "Insert". Then click on the "Zoom to Fit" button or set the bounds of the window to 0 ns to 100 ns. You should end up with a visualization like below.

      You can see in this example that the circuit is working properly. The output F is high when A and B are both low (0) or both high (1), and F is low (0) when A and B are not the same value.

Test a Circuit with the Altera DE0 Board

The Altera DE0 board contains a programmable Field Programmable Gate Array [FPGA]. An FPGA is an electronically configurable set of gates (truth tables) that can be programmed to emulate very complex digital circuits, including CPUs. The Quartus software can compile a digital circuit into a form that can be downloaded onto the FPGA.

The Altera DE0 board contains many different input and output devices, including push-buttons, switches, LEDs, and 7-segment displays. We will be using these input and output devices to control and evaluate our circuits.

You can find the documentation for the DE0 board here. Pages 25-29 specify which output pins control which I/O devices.

In order to program the board, you need to follow these steps.

1. Compile the code with Quartus (Quartus compiles the code for download onto the board, whereas ghdl compiled it for simulation). Press the purple arrow to do so.

   

2. Open up the Assignment:Pin Planner window. If you have set up the input and output pins of your circuit correctly, they will show up at the bottom of the window. In the Location column, specify the pin for each input and output. For the simple circuit above, for example, you can use the first two switches (PIN_J6 and PIN_H5) as the inputs and the first green LED (PIN_J1) as the output.

   Once you have specified the pins for all inputs and outputs, close the Pin Planner window and compile your circuit. Any time you change pin assignments, you must recompile.

3. Second, plug the DE0 board into an available USB port, if it is not already plugged in. If no lights appear, then click the red button to turn on the board. The default program should produce flashing lights.
4. Third, open up the Tools::Programmer window. If the window says "No Hardware" then click on Hardware Setup, click on the popup menu that says "No Hardware" and select the USB Blaster. Then close the Hardware Setup window.

   At this point, if the Start button is available, click it and it should program the board. If the Start button is not active, then click Select File, navigate to your output_files directory and select the .sof file corresponding to your circuit. If the Start button is now active, click Start and it should program the board. You will know the board has been programmed when the default FPGA program with the flashing lights stops.

   If clicking on the Start button does nothing, please contact me and let me know the (1) name of the machine on which you are working and (2) whether any error messages show up in the Quartus log window.

5. Once the board is programmed, you can control your circuit by modifying the switches you set up to control the circuit inputs. In the case of the simple circuit above, if the two switches are both 0 or both 1, then the LED should light up.

   Here is a demo if you really want to watch one. I warn you that production values are extremely low.

6. When you are done with the board, please use the red button to turn it off.

We will make an animation of the simulation output.

Our goal is to make an animation that shows what the board would be doing if you were controlling it with the inputs defined in the test-driver (testbench.vhd). Stephanie wrote a Python program to animate inputs (switches and key button) and outputs (LEDs and 7-segment displays). To use that program, you need the .vcd file that was generated by ghdl. This tells us what values the signals have at each point in time. You will also need to define which signals are mapped to which elements on the board.

1. vcd_movie.py is the Python program that uses the TK library to make a GUI that animates a simulation. The top frame in the GUI has the same input/output elements on the DE0 boards, including 7-segment (also called hexadecimal) display (like a digital clock), switchs, green LEDs, and buttons. The middle frame has a timeline so that you can see which step of the simulation is being shown at any given time. The bottom frame as the control buttons -- use Start to begin an animation, Pause to pause it (and Start to restart), and Reset to set the time back to 0. You can control the speed of the animation with the slider (slower to the left, faster to the right).

   Note that not all elements of the board are used in this lab, but they will be eventually. Today, we will be using one green LED and two switches.
   

2. Next, make a file named testbench_mapping.txt in the same directory as testbench.vcd. You can use Quartus as your editor or a simpler program (e.g. vi). Map signal A to the switch that is second-from-the-right, signal B to the rightmost switch, and signal F to the rightmost green LED. The contents of the file are

   # signal name, bit in signal, type of board widget, which bit in board widget
   A,0,switch,1
   B,0,switch,0
   F,0,LEDG,0
   

   The rules for this text file are:

   • # at the beginning of a line indicates a comment
   • Each line specified how one bit of a signal is mapped to one board element
   • Each line is comma-separated with the following values
     • signal name: This must match the name of one of the signals in the top-level vhd file (testbench.vhd, for this lab).
     • signal bit: This is the index of the bit we are mapping. If the signal is only one bit (as in this lab), then just write "0". If the signal more than one bits, e.g. it is defined like this

                signal num : unsigned(3 downto 0);
               

       then specifying bit 0 means signal(0), i.e. the rightmost bit of the signal. You can specify bit 0, 1, 2, or 3 for the signal named num.
     • board element name: This is one of
       1. switch: for the switches
       2. hex: for the 7-segment displays
       3. LEDG: for the green LEDs
       4. button: for the buttons
     • board element index: specifies which element, e.g. if it is 0 and the board element name is hex, then it is the rightmost 7-segment display. Board elements are numbers right to left, just like bits are.
     • segment index: specifies which of the 7 segments in the 7-segment display. This is relevant, only if the board element name is hex.
   • Download the Python code vcd_parser.py and vcd_movie.py and place them into your CS232 directory. Please let me know when you run into problems with it and I will do my best to fix them ASAP. I will put the most recent version on the web, so you can download it. So that you don't have copies of it proliferating, I think it is a good idea to put it in a top-level directory and replace it with updates.
   • Change to the directory with the Python code, and run vcd_movie.py with the vcd and mapping files. For me, the command is

     python3 vcd_movie.py lab01/testbench.vcd lab01/testbench_mapping.txt
     

     There are three control buttons

     • Start: begin the animation
     • Pause: pause the animation
     • Reset: Reset the time back to the beginning. As of the beginning of the semester, this doesn't work well unless you press the Pause button first.
     and a slider. The slider controls the amount of time between each timestep. It is only approximate. When the simulation is running, the current time step is indicated by the red bar on the time-line.

When you have completed the lab assignment, go ahead and get started on the first project.