Lab 1: Five-Bit Numeric Display
Part C: Build System
Lab 1 is designed to give you experience designing, implementing, testing, and prototyping a simple Verilog hardware design. This lab will primarily leverage concepts from Topic 2: Combinational Logic and Topic 3: Boolean Algebra.
You will be implementing a five-bit numeric display that takes as input a five-bit binary value and displays this value as a decimal number using two seven-segment displays. Your implementation will exclusively use combinational logic gates. This five-bit numeric display will be reused extensively across all of the remaining labs. The lab includes five parts:
-
Part A: Unoptimized and Optimized Display
- Must be completed individually
- Due 9/13 @ 11:59pm via GitHub
- Students should work on Part A before, during, and after your assigned lab section during the week of 9/7
-
Part B: Breadboard and FPGA Primer
- Done with randomly assigned partner
- Due week of 9/7 during assigned lab section
- Even though completed with a partner, every student must turn in their own paper check-off sheet in their lab section!
-
Part C: Build System
- Must be completed individually
- Due 9/17 @ 11:59pm via GitHub
- Students should work on Part C before, during, and after your assigned lab section during the week of 9/14
-
Part D: FPGA Prototype
- Done with randomly assigned partner
- Due week of 9/14 during assigned lab section
- Even though completed with a partner, every student must turn in their own paper check-off sheet in their lab section!
-
Part E: Report
- Done with same partner as in Part D
- Due week of 9/14, three days after lab section @ 11:59pm via Canvas
- Post-lab survey on Canvas is due at the same time as the report
This handout assumes that you have read and understand the course tutorials and that you have attended the discussion sections. This handout assumed you have successfully completed Part A. You should have already cloned your individual remote repository, so use git pull to ensure you have any recent updates before working on your lab assignment.
where netid should be replaced with your NetID.
1. Automated Build System
Constantly entering commands on the command line to lint, compile, and run tests can quickly become tedious. In the third discussion section, students learned about a build system we can use to automate this process. We have now pushed this build system into student's repos so that students can use the build system in Part C.
The automated build system involves the following new files in your repo:
Makefile.in: Makefile for the build systemconfigure: Configure script for the build systemconfigure.ac: Used to generate the configure scriptscripts: Scripts used by the build system
It will also add a lab1.mk file to the lab1 subdirectory which is
used to tell the build system about all of the files in Lab 1.
When using the automated build system we always work in a build
directory. This simplifies keeping the generated files separate from the
source files. You should be able to trash the build directory at any time
for a "clean build". This is particularly useful if something seems to be
going seriously wrong; a "clean build" is sometimes all you need to fix
the issue.
1.1. Configuring the Automated Build System
Here is how to create the build directory and configure the automated build system.
1.2. Building Tests
Here is how to build and run the tests for the unoptimized binary-to-seven-segment converter.
% cd ${HOME}/ece2300/lab1-netid/build
% make BinaryToSevenSegUnopt_GL-test
% ./BinaryToSevenSegUnopt_GL-test
% ./BinaryToSevenSegUnopt_GL-test +test-case=1
% ./BinaryToSevenSegUnopt_GL-test +test-case=2
% ./BinaryToSevenSegUnopt_GL-test +test-case=2 +dump-vcd=waves.vcd
The build system takes care of using Verilator to lint your design, using our own custom linter to check rules specific to ECE 2300, and using Icarus Verilog to compile your design into a simulator. Here is how to build and run the remaining tests.
% cd ${HOME}/ece2300/lab1-netid/build
% make BinaryToBinCodedDec_GL-test
% make BinaryToSevenSegOpt_GL-test
% make DisplayUnopt_GL-test
% make DisplayOpt_GL-test
% ./BinaryToBinCodedDec_GL-test
% ./BinaryToSevenSegOpt_GL-test
% ./DisplayUnopt_GL-test
% ./DisplayOpt_GL-test
It can be convenient to build and run a test using a single command line like this so you can just use the up-arrow key to quickly rebuild and rerun a test.
% cd ${HOME}/ece2300/lab1-netid/build
% make BinaryToSevenSegUnopt_GL-test && ./BinaryToSevenSegUnopt_GL-test
You can build and run all of the test with the check target like this:
1.3. Building Interactive Simulators
You can build and run the interactive simulator like this:
2. Lab Code Submission
All you need to do for Part C is make sure your code works with the
automated build system. Once you are sure it is working, push your code
to GitHub. GitHub Actions will use the automated build system to build
and run your tests. You can push your code as many times as you like
before the deadline. Students are responsible for going to the GitHub
website for your repository, browsing the source code, and confirming the
code on GitHub is the code they want to submit is on GitHub Be sure to
verify your code is passing your tests both on ecelinux and on GitHub
Actions. Your design code will be assessed both in terms of code quality,
verification quality, and functionality.
2.1. Part A Revisions
If your design is failing some tests from Part A, then you should fix whatever is wrong. If your design is passing your tests but failing our tests you should browse the staff tests to see how to improve your own testing. Fixing whatever is wrong now can improve your code functionality score and also ensures that you can use your work from this lab in future labs.
To revise your submission, simply push any updates to your tests and/or your hardware designs to GiHub just like normal. You do not need to switch branches; just push your changes to the main branch like normal. Make sure your updates are passing all of your (potentially updated) tests on the main branch on GitHub Actions.
All Part A revisions need to be finalized by the due date for Part C.
2.2. Code Quality
Your code quality score will be based on how well you follow the course coding conventions posted here:
You can take advantage of the ECE 2300 formatter like this:
We recommend committing your code first before you run the ECE 2300 formatter so you can roll back if the formatter does something you do not like.
Remember that the ECE 2300 formatter does not format everything! You will need to do some work after running the formatter to ensure a high code quality score.
2.3. Verification Quality
Verification quality is based on how well your testing enables making a compelling case for correctness. In this lab, we are using exhaustive testing so achieving high verification quality should be straight forward. Verification quality will be based on your Part A submission.
2.4. Functionality
Your functionality score will be determined by running your code against a series of tests developed by the instructors to test its correctness. Note that we will be using the automated build system to test your final code submission as shown below.