Lab 1 - SystemVerilog Review

Lab #1 - SystemVerilog Review

In this lab you will become familiar with the Vivado tools used in ECEN 323, the ECEN 323 lab submission process, and review your SystemVerilog RTL coding skills that you learned in ECEN 220. You will be using SystemVerilog to design all of your laboratory assignments this semester. It is essential that you have strong RTL SystemVerilog design skills. In this lab you will review your SystemVerilog RTL design practices and strengthen your RTL skills by creating several SystemVerilog modules. You will demonstrate your SystemVerilog skills by downloading a circuit on the Basys3 FPGA board used in ECEN 220. Much of this laboratory assignment will be a review and the amount of time you spend on this lab will depend on you famliarity with Unix, GitHub, and your SystemVerilog RTL design experience.

Avg Hours: 3.6 (Winter 2021)

Learning Outcomes

  • Understand how to complete and submit lab reports
  • Review how to simulate, synthesize, and generate bitstream files from a SystemVerilog file
  • Review your SystemVerilog design skills by modifying an existing SystemVerilog file
  • Review your understanding of the Vivado design tools by simulating your SystemVerilog module
  • Learn how to download your SystemVerilog module onto the Basys3 FPGA board

Preliminary

Each laboratory assignment contains a “Preliminary” section that involves tutorials, training, and reading that will help you get started with the lab before you show up for the lab assignment. You are encouraged to read and start the laboratory preliminary before you show up to the lab. This preliminary section will guide you through the laboratory completion and submission process and introduce you to the BYU ECEN Digital Laboratory.

Slack Lab Channel

There will be a dedicated channel in the class Slack workspace for each laboratory assignment. You will automatically be added to this channel when it is created. This Slack channel is used to provide updates or clarification on the lab as problems are discovered. Students are encouraged to ask questions about the lab on this channel and provide answers to other students. The TAs and instructor will monitor this channel and provide responses as needed.

What is the preferred way to communicate with the TAs and instructor for laboratory assignments?

Laboratory Completion Instructions

Begin this preliminary by carefully read through the instructions for completing lab assignments. After reading these instructions, answer each of the following questions in your lab report (i.e., Learning Suite).

What portion of your composite laboratory grade is the “Lab Report” component?

How do you submit a laboratory report in this class?

When are laboratory lab reports due?

Are late lab reports accepted?

How are filess submitted for the passoff section of the lab?

When are laboratory Pass Offs due?

Are late lab passoffs accepted?

ECEN Digital Lab

You will use the computers in room 423 EB to access the software for designing digital hardware. To access these computers, you will need an active CAEDM account. Request a CAEDM account if you do not already have one.

When in this room, you are required to follow all CAEDM policies. Review these policies and answer the following question:

Which activities are acceptable in the Digital Lab?

Unix

The computers in this lab are configured with Linux and you will be required to navigate the Unix command line to run tools, manage files, and complete laboratory assignments. If you are unfamliar with Unix, you may want to refer to the ECEN Linux Introduction laboratory to prepare yourself for using Linux. This laboratory includes links to a number of good tutorials for improving your Unix skills. The following ECEN 220 page contains a nice overview of the most common Unix commands you will use in this course.

GitHub

GitHub will be used extensively in this class for submitting and grading your laboratory files. You will be required to create a GitHub classroom repository to store your laboratory files. Carefully read and follow the instructions in the GitHub Setup Guide to setup your class repository and import the initial class code. After completing the instructions in this tutorial and creating your GitHub repository, provide the remote GitHub repository URL on Learning Suite. Your response should be in the form of a ‘ssh URL’ such as: git@github.com:byu-ecen323-classroom/323-labs-wirthlin.git (although you will have a different repository name in the same repository classroom). This ‘ssh URL’ will be used by the grading scripts to clone your repository.

Provide the URL of your class GitHub repository.
Note that it is essential that you copy this URL correctly. The TA grading scripts will use the URL you provide here for extracting your code. You will face a 20% penalty on this lab if this URL is entered incorrectly or if the URL is not accessible. Make sure the URL you provide actually works and points to your classroom repository before submitting your lab report.

You will need to become familiar with using GitHub for submitting your laborator files. To learn some of the most basic functions of Git, complete the GitHub Basic Tutorial. As part of this tutorial you will create a file named ‘github_tutorial.txt’ and commit it to your repository.

Make sure the file ‘aboutme.txt’ is committed in the ‘lab01’ directory of your repository.

Note: This green text above indicates that the ‘aboutme.txt’ must be included in your passoff GitHub repository when you submit your lab. This file should contain the information requested during the tutorial and will be reviewed by the TAs.

After reading the instructions on GitHub, answer each of the following questions in your lab report to demonstrate your understanding of Git and its use in the class.

What type of git repository will you be creating for this class?

What git commands should you run to update the starter code in your repository throughout the semester?

Which git commands should you use when submitting your files for the passoff portion of the lab?

Exercises

Exercise #1 - Using the Vivado Design tools

In this course, you will use the Xilinx Vivado design software to design digital circuits and then test those designs on the circuit board. This software is installed on the lab machines in the EB lab for this class. It is necessary that you know how to run these tools and become very familiar with these tools. In this exercise you will learn how to run the Vivado tools in the digital lab and create a simple design to demonstrate your ability to run the tools. The instructions for setting up your environment for Vivado are described in the ECEN 220 Lab 0 write up under the section titled “Setup Xilinx Design Tool Environment”. You may also access the tools remotely or install them on your own computer. The following page describes Altermative Vivado Tool Use Options. While the use of tools outside of the digital lab are possible, they are not supported by the TAs.

Begin by configuring your environment to access the Vivado tools and run the Vivado tool.

Indicate the version of Vivado that is installed in the digital lab.

Your class repository should contain a directory lab01 that contains a number of files that will be used in this exercise. Make sure you have access to this directory in your local repository as you will need these files to complete several of the lab exercises. For this exercise, you will use the files in the lab01\buttoncount directory. This example includes a SystemVerilog file that defines a simple counter circuit that counts the number of times a button has been pressed on the Basys3 board. In this exercise you will create a project in Vivado using the files in this directory and review the code in this example.

Vivado Projects

The Vivado design tool organizes FPGA designs around the concept of a Vivado ‘project’. A Vivado project includes all of the sources and settings necessary to specify the design, simulate the design, and implement the design on the FPGA. The project also generates a lot of intermediate files during the simulation and implementation process. Each laboratory assignment will involve the creation of one or more Vivado projects for FPGA design. Each Vivado project is given a unique project name and is stored in a specific project directory. One of the challenges in working with Vivado projects is managing the source files used for a project using a Version Control System like GitHub along with all the intermediate files generated in the implementation process.

For this class, you are required to organize your Vivado projects as follows:

  • Save all project source files within specific directories within your repository (the specific location will be defined for each lab)
  • Name the Vivado project directory “proj” and place this directory as a sub-directory where your project sources are stored. You should not store your source files within the project directory as often happens when you create new files from scratch using the Vivado source editors.

Begin by creating a new project named ‘ButtonCount’ in the lab01/buttoncount/proj directory of your repository. You can create a new project in two ways. First, you can create the project using the GUI by following the Creating a Project within Vivado tutorial on the 220 website. The part that should be specified when creating the project is “xc7a35tcpg236-1”. Second, you can you can create a project from the Vivado command line by executing the following tcl commands in the Vivado command line window:

#create_project -force [project name] [project directory]
create_project -force ButtonCount ./proj
# Set the part property for the project to the part on the Basys3 board
set_property "part" "xc7a35tcpg236-1" [get_projects [current_project]]

The TCL commands shown above assume that the current directory in the Vivado command window is the lab01/buttoncount directory that contains the source files for the project (you can determine the current directory of this shell by using the pwd command on the command line). You may need to change directories in this window before executing the command using the cd command. Alternatively, you can change the location of the project window when executing the create_project command.

Once you have created your project, you should change the default settings of several parameters within Vivado. A script has been created for at /resources/new_project_settings.tcl in the class repository to make these changes for you. When in the lab01/buttoncount directory, run this script as follows to change your default project settings:

source ../../resources/new_project_settings.tcl

The ButtonCount design includes two SystemVerilog files: ButtonCount.sv and OneShot.sv (both in the lab01/buttoncount directory). The ButtonCount.sv file contains the top-level button counter logic and the OneShot.sv file contains the logic for implementing a simple one-shot pulse detector. You will need to add both files to the project in order to build the design in the FPGA. Like creating a project, you can add these files in the project in two different ways. First, you can add the file using the GUI as described by the ECEN 220 tutuorial. As an alternative, you can add files to your current project on the Vivado command line using the following tcl command:

add_files ButtonCount.sv OneShot.sv

Note that if the current directory of the Vivado command line window is not lab01/buttoncount then you will need to change to that directory or specify the path of the ButtonCount.sv file.

It is convenient to create a .tcl file that will do all of these commands for you in a single script. You can add this file to your repository and create a new project without using the GUI. The following example demonstrates the commands you would use to create your project in a single .tcl script:

create_project -force ButtonCount ./proj
set_property "part" "xc7a35tcpg236-1" [get_projects [current_project]]
source ../../resources/new_project_settings.tcl
add_files ButtonCount.sv OneShot.sv

After adding the file to your project, open the two files in the Vivado text editor to review the contents. Carefully review the text of this SystemVerilog files to familiarize yourself with the SystemVerilog syntax and the coding style. The top-level ButtonCount.sv file contains a counter to keep track of the number of button presses and the file OneShot.sv contains the state machine that is used to make sure that the counter is incremented only once each time the button is pressed. Carefully review the code and find each of these components. A summary of these components is described below:

ButtonCount.sv

The code in this top-level design includes a 16-bit counter that will increment every time the button is pressed. It also includes a synchronizer to synchronize the button signal to the global clock signal. The counter is reset with a synchronous reset signal (the center button). The output of the counter are tied to the LEDs on the Basys3 board.

What line of code in this file describes the logic used to assign the count value to ‘zero’ when the ‘rst’ signal is asserted? .

OneShot.sv

This file includes a state machine that is used to detect the first clock cycle in which the up button transitions from ‘0’ to ‘1’. The reason this state machine is needed is because we do not want to increment the counter for every clock cycle in which the button is pressed. If we did this, the counter would increment too fast for us to see any impact. This state machine keeps track of what the history of the button press has been and then generates an output signal, ‘inc_counter’, that is asserted for only one clock cycle when the button is first pressed. This is sometimes called a “one shot” detector because we want only one clock cycle signal for a long button press.

The state diagram for this state machine is shown below. This state machine has three states: ZERO, INC, and ONE. In the ZERO state, the state machine is waiting for the input signal ‘inc’ to go high. As long as ‘inc’ remains low, the state machine remains in this state. When the input ‘inc’ goes high, the state machine will move to the INC state. During the INC state, the Moore output signal ‘transition’ is high indicating that the input has made a transition from 0 to 1. The state machine will transition from the INC state back to the ZERO state if the ‘in’ signal is zero, otherwise it will move to the ONE state (i.e., when ‘inc’ is 1). The state machine will remain in the ONE state until the ‘inc’ signals returns back to zero. This state machine includes a synchronous reset signal named ‘rst’ that will return the state machine back to the ZERO state on the next positive clock edge.

After reviewing the code for this ButtonCount circuit, determine the values of the ‘inc_count’ signal and the counter value by completing the waveform below.

Complete the questions about the waveform in the laboratory report.

Exercise #2 - Vivado Simulation with TCL Scripts

In this next exercise, you will use the Vivado simulator to validate the function of the ButtonCounter circuit. The Vivado simulator will be essential for you to test your circuits throughout the semester and it will be essential for you to learn how to use the Vivado simulator well. Open the Vivado simulator within your project to begin simulation of the circuit. You may want to review the 220 Starting the Vivado Simulation Tools tutorial to help you get started. There are a number of resources that may help you as use the simulator:

You can control the simulator using the GUI by clicking various buttons on the simulator tool or by executing “TCL” simulation commands (TCL is a scripting programming language that is often used in design tools like Vivado). You can type the commands by hand or execute TCL simulation scripts that contain a list of TCL simulation commands. For this exercise, you will be simulating your circuit using TCL commands. If you are unfamiliar with using TCL for simulation, you may want to review the 220 TCL 1 and the TCL 2.

A TCL simulation script, ButtonCount_sim.tcl, is included in the local repostory to simulate the input waveform provided to you in the previous exercise. You will need to execute this simulation script within the simulator to simulate the design. You can execute the script one of two ways:

  • Execute the command from the Tcl command line
    • Change the current directory of the Tcl Console to the directory: cd <Path>
    • Execute the Tcl script: source ButtonCount_sim.tcl
  • Execute the command through the GUI
    • Select the menu option: Tools->Run Tcl Script
    • Select the script in the file dialog box

Execute this script and review the waveform output.

Answer the questions in the lab report regarding the results of this waveform out.

Exercise #3 - Synthesis, Implementation, and Bitfile Generation

In this exercise, you will go through the steps required to implement your ButtonCount module and target it for the Basys 3 FPGA board. As you may remember from ECEN 220, there are many steps involved in preparing your SystemVerilog module for the Basys 3 FPGA board. These steps will be summarized below.

Basys 3 FPGA Board

We will be using the Basys 3 FPGA board for many of the laboratory assignments in this class. This is the same board used in the ECEN 220 class so you may already be familiar with its operation, capabilities, and functions. If you are unfamiliar with the Basys 3 board, you can review the features of this board at the following link: Details about the Basys3 board.

The inputs and the outputs of the ButtonCount module need to be connected to specific pins on the FPGA so that they are hooked up to the proper buttons, leds, etc. An ‘.xdc’ constraints file is used to map the top-level input/output signals to specific pins on the FPGA. The file ButtonCount.xdc has been created to demonstrate how this is done. This file uses the following input/output resources on the Basys3 board:

  • The global clock input ‘clk’ is connected to the 100 MHz clock
  • The ‘rst’ input is connected to the center button (BTNC)
  • The counter outputs are connected to the light emitting diodes (LEDs) LD15-LD0 (i.e., count[15], count[14],…,count[0]) You will need to add this file to your project before proceeding with the implementation steps. You can add the constraints file using the GUI by following this tutorial or you may add it on the command line by executing the following TCL command:
    add_files -fileset constrs_1 ButtonCount.xdc
    

You will need to create/modify an .xdc file in the future labs. The following tutorial describes how to create an .xdc file (although you don’t need to do this for this exercise). A comprehensive .xdc file has been included in your repository that you can use as the base for your future FPGA designs (see resources/Basys-3_323.xdc).

SystemVerilog Synthesis

The logic synthesis step will take your SystemVerilog code and synthesize a digital circuit from it. The messages generated by the synthesis step are very important and it is essential to review the synthesis logs carefully. The following tutorial describes how to run the synthesis step.

The synthesis step may introduce a number of errors and warnings. These errors must be resolved and the warnings must be understood before proceeding. Carefully review the logs of your synthesis report. Although this SystemVerilog file has been prepared for you and should not have any synthesis errors, you should familiarize yourself with the output of the synthesis command. You may want to refer to the following reference of synthesis warnings to learn about common synthesis warnings you may experience.

Implementation

The next step in the process is to implement the synthesized logic onto the FPGA found on the Basys 3 board. A tutorial describing how to run this tool is provided on the 220 web site. After completing the implementation step, summarize the timing and resource utilization of your design. Details on how to determine the resource utilization and circuit timing can be found at the following tutorial link

Indicate the number of resources consumed by this design in the laboratory report.

Determine the “Worst Negative Slack” or WNS of this circuit.

Bitstream Generation

Finally, create a bitstream of your design by running the generate bitstream tool. Executing the Bitstream Generation Step

Bitstream Download

For the final exercise of this laboratory, download the bitfile onto your Basys 3 board. You will need to download this bitfile onto your own board and make sure it works. The following tutorials may be helpful in this process:

Download the bitstream for your TransitionCount circuit to a Basys 3 board. Make sure the board operates correctly by pressing BTNU to see the LED count increase. Also, press BTNC to reset to make sure the counter resets.

Exercise #4 - Up/Down Button Counter

The final exercise of this lab is for you to create a new SystemVerilog file that performs both ‘up’ counting and ‘down’ counting (i.e., an up/down counter). Start this exercise by copying the ButtonCount.sv file into the lab01/ directory (one directory higher than the lab01/buttoncount directory) and name it UpDownButtonCount.sv. Modify this file to incorporate the following changes:

  • Add the additional input ports named “btnd”, “btnl”, and “btnr” for the “Down button”, “Left button”, and “Right button.
  • Add a 16-bit input port named “sw” for the 16 switches on the Basys3 board
  • Add three more “One Shot” module to generate a one shot signal for each of the three button inputs (i.e., for “btnd”, “btnl”, and “btnr”).
  • Modify the counter logic to operate as follows:
    • decrement the counter by 1 every time ‘btnd’ button is pressed.
    • increment the counter by the value indicated on the switches every time ‘btnr’ is pressed
    • decrement the counter by the value indicated on the switches every time ‘btnl’ is pressed

In this course you are required to follow a coding standard for your SystemVerilog code. A coding standard is used in this course for several reasons. First, having your code written using a clear and consistent standard makes it much easier for the instructor and TA to help you as you debug your logic. Second, code written using a consistent standard is much easier to grade. Third, coding standards are used regularly in industry and it is good to practice using coding standards. Briefly review the coding standard before answering the preliminary questions (there will be several coding standard questions in the preliminary question block). This example follows this coding standard. Also, there is a dedicated web page for SystemVerilog resources you can use to brushen up your understanding of SystemVerilog.

You will need to include the UpDownButtonCount.sv file as part of your “Pass Off” below.

Simulation

Once you have modified your new SystemVerilog file, create a new project for this file and add your new file to this new project. Resolve any errors that show up in your source window. When your errors are removed, simulate your new file (the compiler may find additional errors when you try to simulate). Once you the simulator has started, copy the .tcl simulation file ButtonCount_sim.tcl that you were given in the previous exercise and name the new .tcl simulation file UpDownButtonCount_sim.tcl. Modify this file to simulate both up and down counting (Note: there is a coding standard for .tcl files - refer to the coding standard guidelines to make sure you code your .tcl file properly). Include at least three “down” button presses to decrement the counter and at least two more “up” button presses to increment the counter.

You will need to submit the UpDownButtonCount_sim.tcl file as part of your “Pass Off” below.

Implementation

Once you have successfully simulated your new file, you are ready to implement the circuit on the FPGA. Before proceeeding, you will need to create a new .xdc file for your design. Copy the ButtonCount.xdc file used in the previous exercise and name the new file UpDownButtonCount.xdc. You will need to change this new file by removing the comment (‘#’) on the all the lines associated with the three additional buttons and 16 additional switches (two lines per pin).

You will need to include the UpDownButtonCount.xdc file as part of your “Pass Off” below.

After creating your new .xdc file, add it as a constraint file to the project, implement the design and generate a programming bitstream.

Indicate the number of resources consumed by your new design in the laboratory report. <!–

–>

Determine the “Worst Negative Slack” or WNS of this circuit.

Download

Once you have successfully generated a bitstream for your new Up/Down button counter, download this bitstream to your Basys3 board. Experiment with your circuit and verify that (1) you can count up, (2) that you can count down, and (3) that you can reset the counter by pressing the center button. You will need to take a picture of your board with the LEDs showing the value 0xFFFB (i.e, a negative 5). You can get this value by pressing the down button five times or reseting the counter and subtracting five with the switches. Convert this picture to a JPEG file format and name this file ‘UpDownButtonCount.jpg’.

You will need to include the UpDownButtonCount.jpg file as part of your “Pass Off” below.

Pass Off

The final step in the laboratory process is to complete the ‘pass off’. There are several important steps involved in every lab passoff. This section will describe how to properly submit your passoff.

First, you must prepare your repository with your submission files. For this lab, you should have all of the following files in your lab01 directory of your repository:

  • UpDownButtonCount.sv
  • UpDownButtonCount_sim.tcl
  • UpDownButtonCount.xdc
  • UpDownButtonCount.jpg
  • aboutme.txt

If these files are not in this directory then move them here. In practice, you should keep the working files of your lab in the lab directory rather than moving them from some other location at the time of passoff.

Once all your files are physically in your local repository, you need to make sure they are ‘added’ in your repository. If they are not added, add them using the git add command. The git status command can be used to see which files are not a part of your repository. NOTE: It is easy to accidentally add unnecessary files to your repository. Be careful that you do not inadvertendtly commit your Vivado project files or other unnecessary intermediate files. You will receive a 50% penatly on this and every other lab if you include Vivado project files in your repository.

After adding your files, commit the files to your repository using the git commit command. Finally, you need to tag your repository with the lab1_submission tag:

git tag lab1_submission
git push origin lab1_submission

Note that you will need to use the -f option if you are going to re-tag your repository (for example, if you need to change files after you already tagged the repository).

At this point your laboratory pass off is submitted. Before moving on, you should check your submission by running the lab01_passoff.py submission script included with the starter code for the lab. This script will make sure that your files are properly tagged and that your files properly simulate and compile. You are encouraged to update the started code before running the script to make sure you have the lastest copy (this script may be updated if problems in the script are found).

git fetch startercode
git merge startercode/main -m 'Merge starter code for passoff script'

Execute the script while in your local lab01 directory as follows:

python3 lab01_passoff.py -f

This script will check out your remote repository, check for the presence of all lab files, and perform the simulation and synthesis on your design.

More details on the passoff script and problems with the passoff process can be found at the following link.

This same script will be run by the TAs so if it works for you, it will work for the TAs. Check the messages after executing this script to make sure the archive was created successfully. If you have any problems in the execution of this script then you should go back and fix the problem and recommit your submission until the problems are resolved.

Answer the final two questions in your laboratory report:

How many hours did you work on the lab?

Provide any suggestions for improving this lab in the future.



Last Modified: 2022-05-31 12:23:24 -0500