Merge pull request #14 from byu-cpe/2025w

Pit Hw

_documentation/vivado.md

@@ -14,84 +14,21 @@ The Xilinx Vivado software allows you to create digital hardware circuits that c
 
 ## Accessing Vivado 
 
-Vivado is installed in the lab machines.  Alternatively, you can download the Vivado tool on to your personal computer or VM.  
-
-Before you can run Xilinx tools, you must add them to your PATH (this must be done each time you open a new terminal):
-```
-source /tools/Xilinx/Vivado/2022.2/settings64.sh
-```
-
-Then you can run Vivado:
-```
-vivado
-```
-
-**Note: There seems to be an issue with the Vivado installation in the lab that is causing this to fail.  Instead, just run Vivado directly:**
+Vivado is installed in the lab machines.  You can run it like this:
 ```
 /tools/Xilinx/Vivado/2022.2/bin/vivado
 ```
 
-<!-- 
-==== Remote Access ====
-
-There are several lab machines on campus that have the Vivado tool installed.  You can connect to these machines, and run the tool remotely:
-  * The machines are named embed-01.ee.byu.edu to embed-26.ee.byu.edu, and you will login using your CAEDM account.
-  * You will need to be connected to the [[https://caedm.et.byu.edu/wiki/index.php/VPN|CAEDM VPN]] to access them.
-  * You will need to have an X server running on your computer.  If you aren't familiar with this, see [[http://ecen330-lin.groups.et.byu.net/wiki/doku.php?id=xwindows]]
-  * To forward graphics to your computer, you need to provide the ''-X'' option when SSH'ing:
-<code>
-ssh -X <caedm_username>@embed-14.ee.byu.edu
-</code>
-
-**Note:** The first time you connect to these machines, it may take a couple minutes before you are asked for your password.  It is setting up your CAEDM account on the machine.
-
-==== Virtual Machine ====
-
-If you are running on a Mac and want to run Xilinx Vivado software locally, you will need to use a Virtual Machine (VM). Note that you will need about 25-30 GB of free disk space to run the Xilinx software.
-
-You can download and install VMware from [[https://caedm.et.byu.edu/wiki/index.php/Free_Software|BYU]]. Once you download VMWare, install a recent version of Ubuntu and boot the VM. Here are some instructions to follow once you have booted Ubuntu in the VM.
-  - sudo apt-get install open-vm-tools-desktop
-  - sudo apt-get install build-essential
-  - Install CMake from the [[https://apt.kitware.com|Kitware repository]].
-  - Follow [[https://askubuntu.com/questions/580319/enabling-shared-folders-with-open-vm-tools|instructions]] to enable folder sharing. I used the highest voted answer.
-  - Install Xilinx Vivado version 2017.4. You can find the software [[https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vivado-design-tools/archive.html|here]]. Follow the 330 instructions for the installation.
-
-
-
-==== Local Install ==== 
-
-If you are running Linux, you can choose to install the Vivado tools locally.  There are some instructions at the bottom of [[http://ecen330-lin.groups.et.byu.net/wiki/doku.php?id=setup_local|this ECEN 330 page]].  Make sure you install version 2017.4. -->
-
-<!-- 
-===== Running Vivado =====
-
-Each time you open a new terminal, you will need to run this script so that the Vivado tools are accessible on your PATH:
-<code>source /opt/Xilinx/Vivado/2017.4/settings64.sh</code> -->
-
 
 ## Vivado Projects
 
 ### Creating Projects
 In Lab 5 you will need to create a project to simulate and verify your PIT module.
 You should have learned how to create Vivado projects in ECEN 220.  If you want a refresher, you can go back and watch the video on the [Creating a New Vivado Project](http://ecen220wiki.groups.et.byu.net/tutorials/lab_03/00_vivado_project_setup/) page.
 
-In ECEN 220 we had you escalate several Vivado warnings to errors, to help you catch common mistakes in your design.  It would be a good idea to adjust these settings on your Vivado project by running these commands once on each new project:
-```tcl
-set_msg_config -new_severity "ERROR" -id "Synth 8-87"
-set_msg_config -new_severity "ERROR" -id "Synth 8-327"
-set_msg_config -new_severity "ERROR" -id "Synth 8-3352"
-set_msg_config -new_severity "ERROR" -id "Synth 8-5559"
-set_msg_config -new_severity "ERROR" -id "Synth 8-6090"
-set_msg_config -new_severity "ERROR" -id "Synth 8-6858"
-set_msg_config -new_severity "ERROR" -id "Synth 8-6859"
-set_msg_config -new_severity "ERROR" -id "Timing 38-282"
-set_msg_config -new_severity "ERROR" -id "VRFC 10-3091"
-set_msg_config -new_severity "WARNING" -id "Timing 38-313"
-set_msg_config -suppress -id "Constraints 18-5210"
-```
 
 ### Block Design
-*For Lab 6 M1, you will need to create a block diagram based simulation project.  In Lab 6 M2, you will edit an existing block diagram for the hardware on the board that you have been using up to this point in the class.*
+*For Lab 6 M1, you will need to create a simulation project with a block diagram.  In Lab 6 M2, you will edit an existing block diagram for the hardware on the board.*
 
 The block diagram feature of Vivado allows you to visually instantiate and connect different IP and hardware modules.  Some things to note:
   * To create a block design, click *Create Block Design* in the left-side menu of Vivado. The block design should now show up in the *Sources* window.
@@ -103,12 +40,12 @@ The block diagram feature of Vivado allows you to visually instantiate and conne
 
 You will want to commit your Vivado projects to Git.  You shouldn't attempt to commit the actual project files, as there are sometimes hundreds of files.  Instead, you should follow these steps to generate a Tcl file that can be used to recreate your project.  
 
-1. Vivado will attempt to save results of your synthesis run to avoid having to run it again when the project is recreated.  We don't want to save these, so we need to change a setting first.  Right-click *Synthesis* in the left-hand menu and select *Synthesis Settings*.  Locate the *Incremental Synthesis* option, and click the "..." box to change to *Disable Incremental Synthesis*.  Click *OK* to save the setting.
+<!-- 1. Vivado will attempt to save results of your synthesis run to avoid having to run it again when the project is recreated.  We don't want to save these, so we need to change a setting first.  Right-click *Synthesis* in the left-hand menu and select *Synthesis Settings*.  Locate the *Incremental Synthesis* option, and click the "..." box to change to *Disable Incremental Synthesis*.  Click *OK* to save the setting. -->
 1. *File*->*Project*->*Write Tcl*
 1. Make sure to check the box *Recreate Block Designs using Tcl*.
 1. Specify a path to save your Tcl file.
 1. Commit the new Tcl file to Git.
-1. In the future, you can recreate your project by running `vivado -source your_project.tcl`
+1. In the future, you can recreate your project by running `vivado -source your_project.tcl`; however, in Lab 6, there is a provided Makefile that will do this for you.
 
 ## Updating the ECEN 427 Hardware 
 The hardware that you have been using for the labs up to this point is provided in a Vivado project included in the class repository.  All of the necessary files are located in the [hw](https://github.com/byu-cpe/ecen427_student/tree/master/hw) directory.
@@ -146,7 +83,7 @@ or, more simply:
 cd hw
 make ecen427.bit
 ```
-1. The PYNQ board requires the bitstream in *.bin* format.  Go to the *device_tree* folder in the top-level of your repo, and run `make build` to create a new *ecen427.bit.bin* file.  This uses the *bootgen* utility (a Xilinx program), so make sure you have the Xilinx tools sourced in your terminal.
+1. The PYNQ board requires the bitstream in *.bin* format.  Go to the *device_tree* folder in the top-level of your repo, and run `make build` to create a new *ecen427.bit.bin* file.  This uses the *bootgen* utility, a Xilinx program.
 1. Push the new *ecen427.bit* and *ecen427.bit.bin* file up to Github.
 
 

_labs/pit_hw.md

@@ -9,8 +9,9 @@ number: 6
 
 In the real-time clock lab, you used a fixed-interval timer (FIT) from the IP catalog. As you may recall, the FIT generates interrupts at a fixed rate, based upon a single build parameter that cannot be changed once you have built the FPGA hardware. This makes the FIT very easy to use once your system is built, but the FIT is very inflexible. For this lab you are going to build a Programmable Interval Timer (PIT) in SystemVerilog and add it to the hardware system. 
 
-This will be your first opportunity to add new hardware capability to your system. As such, we will start out with a programmable timer, one of the simpler things that you can design and implement.
+The PIT will be an AXI peripheral, allowing the CPU to control the PIT's behavior through memory-mapped registers.  The PIT logic itself is very simple, and you will likely have made more complex designs in a previous class.  The challenging part of this lab is getting the AXI interface correct, which has strict protocol requirements.
 
+You will work with two different Vivado projects in this lab.  The first project will only contain your PIT module and some helper IP to generate AXI traffic.  This project, which is the focus of Milestone 1, will only be used for simulation, as well as checking for synthesis errors.  Next in Milestone 2, you will integrate your PIT into the ECEN 427 Vivado project, which contains the actual hardware system you have been working with in previous labs.  This project will be used to generate a new bitstream that includes your PIT.
 
 ## Specifications 
 
@@ -37,11 +38,21 @@ Your PIT module must include the following:
 ## Implementation
 ### Milestone 1: Simulation Project
 
-To grade your lab, the TAs will run [make sim_pit](https://github.com/byu-cpe/ecen427_student/blob/main/hw/Makefile#L25).  This make target runs Vivado and does two things:
-  1. It sources `sim_proj.tcl`.  
+To grade your lab, the TAs will run the following:
+  ```
+  cd hw
+  make sim_pit
+  make clean
+  make synth_pit
+  ```
+
+The [make sim_pit](https://github.com/byu-cpe/ecen427_student/blob/main/hw/Makefile#L25-L26) target runs Vivado and does two things:
+
+  1. It sources *sim_proj.tcl*, which builds your Vivado project (you don't commit your Vivado project to your repo, only this Tcl file).
       * To create this file, you will need to make your own Vivado simulation project that contains the AXI VIP and your module, connected appropriately.  The Tcl script can then be exported using the *Write Tcl* menu option, as as described on the [vivado]({% link _documentation/vivado.md %}) page.  
       * When this script is run, it should create a Vivado project with a block diagram that uses the AXI VIP to test your module. 
-  2. It sources [run_time.tcl](https://github.com/byu-cpe/ecen427_student/blob/master/hw/run_sim.tcl), which simply runs functional simulation in Vivado.  This means that the Vivado project must be set up with a SystemVerilog test bench that runs the VIP-driven simulation.    
+
+  1. It sources [run_sim.tcl](https://github.com/byu-cpe/ecen427_student/blob/master/hw/run_sim.tcl), which simply runs functional simulation in Vivado.  This means that the Vivado project must be set up with a SystemVerilog test bench that runs the VIP-driven simulation.    
       * The test bench must:
         * Demonstrate writing and reading back the control registers.  When you read back the control register, print it out using `$display`. 
         * Demonstrate writing and reading back the delay-value register.  When you read back the delay-value register, print it out using `$display`. 
@@ -50,9 +61,20 @@ To grade your lab, the TAs will run [make sim_pit](https://github.com/byu-cpe/ec
       * You should have a pre-configured waveform file (.wcfg) set up that has appropriate signals added and organized in a way that the TAs can verify correct operation.  Here is an example:      
       <img src="{% link media/labs/pit_sim.png %}" width="1000">
 
+The [make clean](https://github.com/byu-cpe/ecen427_student/blob/main/hw/Makefile#L7-L8) target removes all the temporary Vivado project files.  You will need to update this command to delete your simulation project files, otherwise it will prevent you from recreating the project in the next step.
+
+The [make synth_pit](https://github.com/byu-cpe/ecen427_student/blob/main/hw/Makefile#L28-29) target runs Vivado and does two things:
+
+  1. Like the above target, it sources *sim_proj.tcl* to create your Vivado project. 
+  1. It performs Synthesis to ensure that your PIT design can be implemented in hardware. Synthesis will check certain design rules that simulation does not check. 
+
+You may want to go back and forth between these two targets as you work on your PIT design.  If synthesis has errors, you will need to fix them and then go back to simulation again to verify that your changes didn't break anything.  Once both of these targets run without errors, you are ready to move on to Milestone 2.
+
+<span style="color:red">**IMPORTANT:**</span> Students frequently forget to commit all necessary files for the TAs to run the above commands.  Make sure you commit your *sim_proj.tcl* file, your waveform configuration file, and any other necessary files to your repository.  It is recommended that your perform a fresh clone of your repository and run the above commands to make sure that everything is committed that needs to be.  
+
 ### Milestone 2: Integration
 
-Once you are confident that your PIT is working correctly, integrate it into the ECEN 427 Vivado project.  See the [Vivado documentation]({% link _documentation/vivado.md %}) for information about creating a Vivado project with the existing ECEN 427 hardware system.  **Make sure you follow the instructions about escalating certain warnings to errors.  This will help you catch problems with your PIT that may have been tolerated in simulation, but will not work when compiling to an actual hardware implementation.**
+Once you are confident that your PIT is working correctly, integrate it into the ECEN 427 Vivado project.  See the [Vivado documentation]({% link _documentation/vivado.md %}) for information about creating a Vivado project with the existing ECEN 427 hardware system.  
 
 Here are some tips to help you integrate your PIT:
   * Make sure you connect up all of the ports