Subitting your ECEN 323 Labs

This page summarizes the submission process using GitHub for ECEN 323 labs. It also provides list of common problems that occur when running the submission scripts.

Submission Process

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

  1. Prepare Files. 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. If you are missing any files or the files are not nammed properly you will have an error.

  2. Update Starter Code. The passoff scripts are constantly being edited and improved. It is possible that the script has been edited to fix a bug since the time you started the lab. You are encouraged to update the starter code in your repository by merging the starter code as follows:
    git fetch startercode
    git merge startercode/main -m 'Merge starter code'
    
  3. Tag and Push Your Repository. After preparing your files, you will need to tag your repository and push your tag to the remote repository. A tag is required for your submission for two reasons. First, it identifies the state of the files as they were when you submitted. You may want to change these files later in the semester and using the tag allows the TAs to capture the files as they were when you completed the submission. Second, when tagging and pushing your repository, the GitHub server creates a “commit date” file that provides a time stamp on the time of your submission. The tag you use for each lab is unique (i.e., labx_submission). The commands for tagging and pushing your repository to your remote is as follows:
    git push
    git tag --force lab1_submission
    git push --force origin lab1_submission
    

    You can re-tag your submission as many times as you like. The date of your submission is based on the last push.

  4. 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/2019.2/settings64.sh
    
  5. Run Passoff Script. At this point you can run the passoff script to test your submission. Executing the passoff script is not required for submission but it is highly recommend as any problems you see in the passoff script will be seen by the TAs. The command for executing the passoff script is as follows:
    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 you will be on your own for running scripts in a windows environment.

Additional options for the passoff script are described below.

Passoff Script Options

The passoff script works as follows:

  1. Clones your remote repository and copy into a temporary repository directory
  2. Performs several tests such as simulation and bitstream on your repository
  3. Summarizes the results of your test

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

  • --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.
  • -f: 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.
  • --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 passoff_temp_dir. 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.

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

“No Commit Time String Found”

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

This warning is due to the fact that there is a 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.

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



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