This page summarizes the submission process using GitHub for ECEN 323 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 of 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 of 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 nammed 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/2023.1/settings64.sh

4. Run Passoff and Submission Script

Each lab contains a python “passoff” script 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 passoff scripts may take some time to complete and involve a number of steps including:

1. Extract your tagged repository into a temporary location
2. Perform one or more simulation steps
3. Perform logic synthesis, mapping, and generate a bitfile

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

python3 lab01_passoff.py -f

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

Completed - No Warnings or Errors

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.

Additional options for the passoff script are described below.

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:

• -f (--force): This option is used to ‘force’ the creation of a temporary directory that already exists. By default, the script will not run if the temporary directory it is trying to creat already exists. This option will delete the directory that already exists before creating the temporary directory.
• --no_tag: By default, the passoff script will tag your repository with the submission date every time the passoff script is run. This option will prevent the script from tagging your repository (this is will preven you from accidentally retagging your repository and chaning the submission time).
• --new_tag: By default, the passoff script will not overwrite an existing tag. This will prevent you from accidentally overwritting an existing tag and submission date. This option will force the script to overwrite an existing tag and submission date when you want to update your submission.
• --clean: This option is used to clean the temporary repository directory or execution directory created during the testing process. The default is to not clean the directories.
• --git_repo: By default, the passoff script will determine the remote repository by querying the repository in the directory where the script is run. This option allows you to specify the remote repository rather than infer it from the current directory.
• --extract_dir: By default, the passoff script will create a directory named /tmp/ecen323_passoff. You can change the temporary directory used for the repository clone using this option.
• --run_dir: By default, the passoff script will run all the executables in the passoff_temp_dir directory. As such, all the logs and temporary files will be put in this directory. This option allows you to change the directory in which the Vivado executables are run.
• --notest: This option is used to skip the passoff steps of the script and only test the ‘clone’ part of the script. This option can be used to see if you have properly pushed your files to the remote repository without running the time consuming pass off tests.
• --local: This option is used to skip the ‘clone’ part of the passoff script and run the passoff code on the files in your current directory. This option is used to test the passoff scripts on the local code and does not test the correctness of the remote repository. Note than when running this option, you should also set the --run_dir flag to specify where the executables should be run.

Common Problems

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

“No Commit Time String Found”

"WARNING: Warning: No Commit Time String Found <Filename>

This warning is due to the fact that the “commit string” as part of your submission was not created. This can be caused by one of two problems:

1. Your ‘github actions’ are not enabled in your repository. See the Git Setup tutorial to see how to enable Github actions on your repository.

2. There is not a sufficient delay between the time you tagged and pushed your repository and when you ran your passoff script. When you push your repository with a tag, GitHub performs an “action” to create a commit file that includes your submission date. This file is the timestamp used for grading your lab. There will be a modest delay between the time you submit your files and the creation of this file. You will get this warning in the passoff script if the GitHub action creating this file has not completed. I suggest that you rerun the script if you get this warning - you should not see this warning the second time.

“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/2023.1/settings64.sh

Untagged Repository

The following example demonstrates what happens when you try to run the passoff script when you haven’t tagged your repository properly:

Cloning repo, tag = lab1_submission 
Cloning into '/home/wirthlin/git/323/323-labs-wirthlin/lab01/passoff_temp_dir'...
fatal: Remote branch lab1_submission not found in upstream origin
ERROR: Clone failed 
ERROR: Failed to clone repository 
Skipping test TCL Simulation (updown_tcl) due to previous errors
Skipping test Synthesis/Bitstream Gen (UpDownButtonCount) due to previous errors
ERROR: Completed - Submission has 2 error(s) 

The key phrase in the error message is the fatal: Remote branch lab1_submission not found in upstream origin message. If you see this message then tag your repository and push it as described above.

Directory exists - use force

ERROR: Target directory /home/wirthlin/git/323/323-labs-wirthlin/lab01/passoff_temp_dir exists. Use --force option to overwrite 
Skipping test TCL Simulation (updown_tcl) due to previous errors
Skipping test Synthesis/Bitstream Gen (UpDownButtonCount) due to previous errors
ERROR: Completed - Submission has 1 error(s) 

This error occurs because the script sees an existing directory named passoff_temp_dir. This error will occur if you run the script multiple times and try to overwrite an existing temporary directory. To solve this problem, use the -f option to force the creation/deletion of the temporary directory.

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 lab01_passoff.py

Missing Submission Files

• Did not include all of the files in your repository (git add)
• Did not name the files as required by the lab

Conflicts with starter code merge