This page summarizes the submission process using GitHub for ECEN 423 labs. Instructions on this page assume you have successfully created your classroom repository as described by the following tutorial. This page also provides list of common problems that occur when running the submission scripts and suggestions for how to fix these common problems.

Submission Process

This section summarizes all the steps needed for a successful passoff.

1. Update Starter Code

The passoff scripts and student support code are constantly being edited and improved throughout the semester. It is possible that the script has been edited to fix a bug since the time you started the lab. You are encouraged to make sure you have the latest starter code in your repository by merging the starter code as follows:

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

2. Commit and Push Lab Files to Your Repository

Make sure your lab includes all the files needed for your submission as described in the lab instructions. All your files should be in the labXX directory of your repository associated with the given lab. If you are missing any files or the files are not named properly your passoff will fail.

It is good practice to regularly commit all your changes into your local repository and push your changes to the remote repository on your main branch. You should run git status -s to see if you have any files that have not been committed to your repository. This command will tell you which files in your directory are not properly committed to the local repository. This command will list the status of each file that is out of sync with your repository. The following symbols are used to indicate the status of files in your repository.

• ??: Indicates the given file is unknown to the repository. Either the file must be added to the repository (by using the git add command) or it should be ignored by updating the .gitignore file in your directory.
• M : Indicates that the given file has been modified. It should be committed to the repository using the git commit command.

git commit -m '<message>' <filename>

Once all of your lab files have been commited to the repository, push your commits to the remote repository:

git push

At this point your remote repository contains your latest updates and is synchronized with the starter code.

3. Prepare Terminal Environment

The passoff scripts use the same Vivado executables that you use with the Vivado GUI. You need to prepare your shell environment to access the Vivado tools before running the script. If you have not prepared your shell, run the following script to add the Vivado tools to your shell path:

source /tools/Xilinx/Vivado/2024.1/settings64.sh

4. Run Passoff and Submission Script

Each lab contains a python “passoff” script named passoff.py that performs two functions: runs the passoff function and tags your repository with a submission date. This passoff script will be run by the TAs during the grading process. You are required to run the passoff script to complete the passoff and make sure your submission is valid. There are many problems that can occur with your submission, and you may have to perform multiple submissions before your passoff script works correctly. There is no penalty for multiple submissions as long as the last submission is before the laboratory deadline.

The command for executing the passoff script for lab 1 is as follows (each lab will have a different passoff script):

python3 passoff.py

You will receive the following message if your passoff script was successful.

Submission successful.

You should resolve any warnings or errors as these suggest problems with your submission.

Note: The submission scripts are intended to be run in Linux on the digital lab machines. The scripts should work on you own computers if you are running Linux, have Python3 installed, and have the Vivado tools properly installed. The scripts are not written to be run on Windows and there is no TA or instructor support to run these scripts in a windows environment. Your submission must successfully complete in a Linux environment to complete the passoff.

Passoff Script Options

Each passoff script works as follows:

1. Tags your repository and saves the submission date for grading
2. Clones your remote repository and copy into a temporary repository directory
3. Performs several tests such as simulation and bitstream on your repository
4. Summarizes the results of your test

You can change the default behavior of the script with several options:

• --required_files : lists the files required in your repository for the passoff.
• --makefile_rules : summarizes the makefile rules you will need to implement to complete the lab
• --make_rule <rule> : run a single makefile rule from the passoff script to make sure the passoff script is happy with your implementation
• --build : Runs all makefile rules from the passoff script to make sure everything is working correctly. This option will perform a ‘clean’ before running the build (unless the --noclean option is also specified).
• --check_repo : Runs all makefile rules from the passoff script to make sure your repository is ready for submission (i.e., all required files are included, there are no uncommitted changes, and there are no intermediate files included in the repository).
• --submit : Submits your lab to GitHub for grading (after performing all the checks). This will perform multiple steps to make sure that (1) your lab builds properly, (2) your repository is ready for submission, and (3) your lab is submitted to GitHub with the appropriate tag.

Common Problems

This section summarizes the common problems students have will executing passoff scripts and their solution.

“ERROR: xvlog not found”

"ERROR: xvlog not found"

This error is due to the fact that the Xilinx Vivado executables are not currently in the PATH environment variable on your currently executing shell. The shell has a variabled named PATH that includes a list of all the directories to search when an executable is run (you can determine what is in your path by running echo $PATH). By default, the Xilinx executables are not in your path. As described in the lab web pages, you need to run a script that adds the Vivado tools to the executable path before running Vivado. You also need to run this script before running the passoff script. The script you need to run is as follows:

source /tools/Xilinx/Vivado/2024.1/settings64.sh

ImportError: No module named pathlib

This error occurs because you are not using python3. Make sure you call the passoff script using python3 rather than just ‘python’:

python3 passoff.py