Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
learn:programmable-logic:tutorials:vivado-hierarchical-blocks:start [2019/09/13 21:58] – Arthur Brownlearn:programmable-logic:tutorials:vivado-hierarchical-blocks:start [2022/10/04 11:38] (current) – external edit 127.0.0.1
Line 1: Line 1:
 ====== Adding a Hierarchical Block to a Vivado IPI Design ====== ====== Adding a Hierarchical Block to a Vivado IPI Design ======
 +
 +In Vivado, a //Hierarchical Block// is a block design within a block design. These blocks allow engineers to partition their designs into separate functional groups. This guide steps through the process of adding a pre-existing hierarchical block to a block design, recreating its example software application, and running the design in hardware.
  
 ===== Inventory ===== ===== Inventory =====
   * A Digilent FPGA development board.   * A Digilent FPGA development board.
   * A computer with Vivado installed.   * A computer with Vivado installed.
-    * //Following the [[:vivado:installing-vivado:start|]] guide will ...// +    * //See the [[:vivado:installing-vivado:start|]] guide for more information.//
-    * //This guide was tested in Vivado 2019.2, other versions of Vivado can work, but support is not guaranteed.//+
   * Familiarity with Vivado IP Integrator and a base block design to work from.   * Familiarity with Vivado IP Integrator and a base block design to work from.
-    * //Following the [[:vivado:getting-started-with-ipi:start|]] guide will ...//+    * //Following the [[:vivado:getting-started-with-ipi:start|]] guide will result in a design that fits all requirements.//
  
 ===== Guide ===== ===== Guide =====
 +==== Setting Up Dependencies ====
  
 +Check if vivado-library is already included in the Vivado project, if it is not, then it should be downloaded:
 +
 +{{https://github.com/Digilent/vivado-library/archive/refs/tags/zmod/v1/2019.1-2.zip|vivado-library-zmod-v1-2019.1-2.zip}}
 +
 +Those familiar with git may want to clone the hierarchies rather than download a ZIP. The dropdown below contains brief instructions.
 +
 +--> Using git to clone the hierarchies #
 +<code>
 +cd (somewhere memorable)
 +git clone https://github.com/digilent/vivado-library -b zmod/v1/2019.1-2
 +</code>
 +
 +Otherwise (if vivado-library is included in the project), use git tools to check out the branch:
 +
 +**Warning!** //If IP from the library are already included in the project, checking out a different branch may cause changes to them. Be careful!//
 +
 +Note that the "branch" selected by this command is a git tag known to work with this documentation.
 +
 +<code>
 +cd (path)/vivado-library
 +git checkout hierarchies
 +</code>
 +<--
 +
 +----
 +==== Adding a Hierarchical Block to a Hardware Design ====
 +<WRAP GROUP> <WRAP COLUMN HALF>
 === 1. === === 1. ===
 +Launch Vivado, then open the Vivado Project the hierarchical block is to be used in, and open the project's Block Design.
  
-Download the [[https://github.com/Digilent/vivado-hierarchies/archive/master.zip|master ZIP archive]] for Digilent's vivado-hierarchies repository and extract it.+**Note**: //The design must contain a processor and a peripheral that can be used for stdout. In the case of Microblaze, a UART IP must be connected to the board's USBUART interface. In the case of Zynq, the PS UART is used by default.// 
 + 
 +Completing the [[:vivado:getting-started-with-ipi:start|]] guide will result in a design that fits the requirements for using these hierarchical blocks. 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:base-bd.png?600 |}} 
 +</WRAP> </WRAP>
  
 ---- ----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 === 2. === === 2. ===
 +In Vivado's TCL Console, enter the following command: <code>source (path)/vivado-library/hierarchies/(hierarchy of choice)/create_hier.tcl</code>
  
-Launch Vivado.+When the script is finished running, the block design will contain a //Hierarchical Block// with several IP inside of it. The IP will be connected to one another and to the block's ports and pins. The contents of the hierarchy can be viewed and changed by expanding it with the "**+**" button. 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:source-create-hier.png?600 |}} 
 +</WRAP> </WRAP>
  
 ---- ----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 === 3. === === 3. ===
- +Check the README.txt file, which can be found in the hierarchical block's folder in vivado-library/hierarchies, for additional information about how the ports of the Hierarchy must be connected to the rest of the design. With this information in mind: 
-Open the Vivado Project you wish to use the Hierarchy in.+   - Connect all of the hierarchical block's AXI interfaces to the processor in the design by clicking on **Run Connection Automation**, and checking the appropriate boxes. These interfaces may appear more than once in the connection automation dialog. Select only one entry for each interface. 
 +   - Connect any interrupts the Hierarchy may have to the appropriate interrupt controller: an AXI Interrupt Controller IP (for Microblaze designs), the Zynq Processing System's irq_f2p port (for Zynq designs). 
 +   - Connect any additional clocks to clocks generated by a Memory Interface Generator or a Clocking Wizard (for Microblaze designs), or a Zynq Processing System (for Zynq designs). 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:connection-automation.png?nolink&600 |}} 
 +</WRAP> </WRAP>
  
 ---- ----
 +
 === 4. === === 4. ===
 +The next step, constraining the Hierarchy's external port/s, has two different Workflows:
  
-Open the project's Block Design.+  - If a board was selected when creating the project, the **Board Flow** can be used for this step. 
 +  - If a part was selected instead of a board, or the Board Flow cannot be used for whatever reason, the **Manual Constraint Flow** should be used instead.
  
 ---- ----
-=== 5. ===+== 4.1 - Creating an External Pmod Port == 
 +Open the dropdown for the chosen Workflow, below, and follow the instructions.
  
-In Vivado's TCL Console, enter the following command: <code>source (Archive extracted location)/(Hierarchy of choice)/create_hier.tcl</code>+**Note**: //This step is only required for Pmod hierarchical blocks. Zmod hierarchical scripts automatically create their external ports. For the purposes of this guide, consider the Zmod's external ports to have been created using the Manual Constraint Flow.//
  
-When the script is finished running, the block design will contain a //Hierarchical Block// with several IP inside of it. The IP will be connected to one another and to the block's ports and pins. The contents of the hierarchy can be viewed and changed by expanding it with the "**+**" button.+--> Board Flow # 
 +<WRAP GROUP> <WRAP COLUMN HALF> 
 +Go to Vivado's //Board// tab and select a Pmod connector to connect to the hierarchical block. Right click on the connector's entry, typically named something like "Connector JA", and select **Connect Board Component**. In the popup window, under //Connect to existing IP//, select the "Pmod_out" interface of the Hierarchy's Pmod Bridge IP. Click **OK**. 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:board-flow.png?nolink&600 |}} 
 +</WRAP> </WRAP> 
 +<--
  
----- +--> Manual Constraint Flow # 
-=== 6. === +<WRAP GROUP> <WRAP COLUMN HALF> 
- +Select the Pmod_out port, then right click on it and select **Make External**. Select the newly created external interface port (named something like "Pmod_out_0") in the design, and give it a memorable name. 
-Make sure your design has a processor, and a peripheral that can be used for stdout. In the case of Microblaze, a UART IP must be connected to the board's USBUART interface. In the case of Zynq, the PS UART is used by default.+</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:make_external.png?nolink&600 |}} 
 +</WRAP> </WRAP> 
 +<--
  
 ---- ----
-=== 7. ===+== 4.2 - Validating the Design and Creating a Wrapper File == 
 +<WRAP GROUP> <WRAP COLUMN HALF> 
 +Regardless of the chosen workflow, validate the block design by clicking the Validate button ( {{:learn:programmable-logic:tutorials:vivado-hierarchical-blocks:validate_button.png?nolink|}} ) and save it. \\ 
 +Then create an HDL wrapper file, if one doesn't already exist, by right clicking on the design in the //Sources// pane and selecting "Create HDL Wrapper". 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:create_wrapper.png?nolink&600 |}} 
 +</WRAP> </WRAP> 
 +---- 
 +== 4.3 - Constraining the Design == 
 +This step works a little differently depending on whether the peripheral targeted by the hierarchical block is a [[zmod:start|Zmod]] or a [[pmod:start|Pmod]]. Select the dropdown for the chosen peripheral:
  
-Check the README.txt file, found in your Pmod's folder in this repo, to find additional information about how the ports of the Hierarchy must be connected to the rest of your design. With this information in mind: +--> Pmod# 
-   - Connect all of the Hierarchy's AXI interfaces to the processor in your design by clicking on **Run Connection Automation**. and checking all appropriate boxes. +<WRAP GROUP> <WRAP COLUMN HALF> 
-   - Connect any interrupts the Hierarchy may have to the appropriate interrupt controller, an AXI INTC IP (for Microblaze designs), the Zynq Processing System's irq_f2p port (for Zynq designs). +If the **Board Flow** was chosen, open the README.txt file in the hierarchical block's folder in vivado-library-hierarchies to determine whether any additional constraints are required. If there are none, //skip the rest of this section//.
-   - Connect any additional clocks to clocks generated by a Memory Interface Generator or a Clocking Wizard (for Microblaze designs), or a Zynq Processing System (for Zynq designs).+
  
----- +When the Hierarchy was created, a constraint file, named "(Hierarchy Name)_Pmod_out.xdc", was imported into the Vivado project. This file contains a template for all required constraints, regardless of the flow used. Open it now from the //Sources// pane, by finding it under //Constraints// and double clicking on it.
-=== 8. ===+
  
-The next step, constraining the Hierarchy's Pmod_out port, has two different workflows.+Constraints required for the **Board Flow** are left uncommented by default.
  
-If you selected a board while creating your project, you can use the //Board Flow// for this step:+If the **Manual Constraint Flow** was chosen, uncomment any commented out lines that start with "set_property", by removing the "#" symbol at the start of each of these lines.
  
---> Board Flow #+The text "%%FIXME%%" is used in the constraint file to indicate places where values specific to the board and design must be manually entered.
  
-  - Go to Vivado's //Board// tab and find the Pmod connector you wish to connect to the Hierarchy. Right click on the entry, typically named something like "Connector JA", and select **Connect Board Component**. In the popup window, under //Connect to existing IP//, select the "Pmod_out" interface of the Hierarchy's Pmod Bridge IP. Click **OK**. +Two types of manually entered values are typical of constraint files in these Hierarchies:
-  - Make sure to validate your block design, save it, and create an HDL wrapper file. +
-  - Check the README.txt file in your Pmod's folder for additional instructions to determine whether any additional constraints are required.+
  
 +Port Names: \\
 +These %%FIXME%%s come after the text "get_ports". The correct values for these FIXMEs can be found by reviewing the HDL wrapper file created in step 5.1. Find the names of the ports of the Pmod_out interface that is connected to the hierarchy within the port map of the HDL wrapper. Enter these names into the corresponding places in the hierarchy's constraints file.
 +
 +Location Constraints: \\
 +These %%FIXME%%s come after the text "PACKAGE_PIN", and are only required in the **Manual Constraint Flow**. The correct values for these FIXMEs can be found by reviewing the master XDC file for the target board. Master XDC files for Digilent boards can be found in the [[https://github.com/Digilent/digilent-xdc|digilent-xdc]] repository on Github. Find the LOC property values that correspond to the Pmod connector that the hierarchical block's Pmod_out port is to be connected to. Enter these values into the corresponding places in the hierarchy's constraint file.
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:edit_constraints.png?nolink&600 |}}
 +</WRAP> </WRAP>
 <-- <--
  
-If you selected a part instead of a board, or otherwise do not wish to use the //Board Flow//, you must create a port to connect to the Hierarchy's Pmod_out port and constrain its pins:+--> Zmod#
  
---> Manual Constraint Flow #+<WRAP GROUP> <WRAP COLUMN HALF> 
 +When create_hier.tcl is run for a Zmod Hierarchical Block, a constraint file is imported which contains template constraints for each external port created by the script. The constraint file is named after the hierarchical block created by the script, followed by the name of the particular Zmod, for example: "ZmodADC_0_ZmodADC.xdc". The constraint file can be found under the Constraints section of Vivado IP Integrato's Sources pane.
  
-  - Select the Pmod_out port, then right click on it and select **Make External**. Select the newly created external interface port (named something like "Pmod_out_0") in the design, and give it a memorable name. +At time of writing, each Zmod Hierarchical Block provides template constraints for each of the Eclypse Z7's Zmod Ports. By default, the Zmod ADC is connected to the Eclypse Z7's Zmod Port A, and the Zmod DAC is connected to Zmod Port B. To connect to a different port, the user need only comment out the section of the xdc corresponding to the default port, and uncomment the section corresponding to the chosen port. 
-  - Validate your design, and save it. If your block design doesn't a wrapper file, right click on the design in the sources pane and select **Create HDL Wrapper**. + 
-  - When the Hierarchy was created, a constraint file, named "(Default Hierarchy Name)_Pmod_out.xdc", was imported into the project. This file contains the constraints required when not using the board flow. Uncomment each line starting with "set_property" by removing the leading "#" symbol. +For other boards, the user must replace the PACKAGE_PIN location constraints for the Zmod ports with the corresponding locations found in the chosen board's master XDC file, which can be obtained through the [[https://github.com/digilent/digilent-xdc|digilent-xdc]] repository on GitHub. 
-  - The text "FIXME" appears in several places in the constraint file. These correspond to places where you will need to manually enter values specific to your board and design. +</WRAP> <WRAP COLUMN HALF> 
-  - Find the correct port names for your Pmod interface by reviewing the port map of the top module near the top of the HDL wrapper file. Enter these port names into the corresponding place in the constraint file (after get_ports, near the end of each line). +{{:learn:programmable-logic:tutorials:vivado-hierarchical-blocks:zmod_constraint.png?600|}} 
-  - Download the master XDC file for your board. Master XDC files for Digilent boards can be found in the [digilent-xdc](https://github.com/Digilent/digilent-xdc) repository on Github. Find the LOC property values that correspond to the Pmod connector of your board that you wish to connect your Pmod to. Enter these values into the corresponding LOC fields in the hierarchy's constraint file.+</WRAP> </WRAP>
  
 <-- <--
  
 ---- ----
-=== 9. === 
  
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +=== 5. ===
 Click **Generate Bitstream**. This process may take some time, depending on the complexity of the project. Click **Generate Bitstream**. This process may take some time, depending on the complexity of the project.
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:generate-bitstream.png?nolink&600 |}}
 +</WRAP> </WRAP>
  
 ---- ----
-=== 10. ===+==== Baremetal Software ==== 
 +<WRAP round center important 660px> 
 +Zmod Hierarchical Blocks are supported in software by the Zmod Library. If using a Zmod, see the [[zmod:zmodbaselibraryuserguide|Zmod Base Library User Guide]], and skip the rest of this guide. If Petalinux support for the added hierarchy is desired, first see the [[programmable-logic:eclypse-z7:customizing-zmods-os|Zmod Petalinux Configuration Guide]] 
 +</WRAP>
  
-Export the hardware design and bitstream to SDK by selecting **File -> Export -> Export Hardware** in the menu bar at the top of the window. In the resulting pop up window, check the **Include bitstream box**, then click **OK**.+<WRAP GROUP> <WRAP COLUMN HALF> 
 +=== 1. === 
 +Export the hardware design and bitstream to SDK by selecting **File -> Export -> Export Hardware** in the menu bar at the top of the window. In the resulting pop up window, check the **Include bitstream** box, then click **OK**. 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:export-hardware.png?600 |}} 
 +</WRAP> </WRAP>
  
 ---- ----
-=== 11. === 
  
-Launch Xilinx SDK by selecting **File -> Launch SDK** in the menu bar at the top of the window.+<WRAP GROUP> <WRAP COLUMN HALF> 
 +=== 2. === 
 +Launch Xilinx SDK by selecting **File -> Launch SDK** in the menu bar at the top of the window. Make sure to set the //<Exported location>// to be the same location chosen in Step 7 above. 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:launch-sdk.png?600 |}} 
 +</WRAP> </WRAP>
  
 ---- ----
-=== 12. === 
  
-Create a new Application Project using the "Empty Application" template. Make sure to check if the Pmod requires you to change any settings or add any libraries to the project. Any requirements are detailed in the README.txt file in the Pmod's sdk_sources folder in this repo.+<WRAP GROUP> <WRAP COLUMN HALF> 
 +=== 3. === 
 +Create a new application project using the "Empty Application" template. Make sure to check if the hierarchical block requires any changes to project settings or if any libraries must be added to the BSP. These requirements, if any, are detailed in the README.txt file in the hierarchical block's sdk_sources folder in the vivado-library-hierarchies folder. 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:new-app.png?600 |}} 
 +</WRAP> </WRAP>
  
 ---- ----
-=== 13. === 
  
-Copy all of the files from your Pmod's sdk_sources folder, then paste them into the empty application's src folder.+<WRAP GROUP> <WRAP COLUMN HALF> 
 +=== 4. === 
 +Copy all of the files from the selected hierarchical block's sdk_sources folder (in the vivado-library-hierarchies folder), then paste them into the application project's src folder. 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:import-sources.png?600 |}} 
 +</WRAP> </WRAP>
  
 ---- ----
-=== 14. === 
  
-Make sure that the development board's programming mode select jumper is set to JTAG. Plug the board into the computer via it's microUSB "PROG" port and power it on.+<WRAP GROUP> <WRAP COLUMN HALF> 
 +=== 5. === 
 +Make sure that the development board's programming mode select jumper is set to JTAG. Plug the board into the computer via its microUSB programming port and power it on. 
 + 
 +Connect the SDK Terminal to the port associated with the board. The **green button** in the Serial Terminal pane is used to launch the //Connect to a serial port// dialog. By default, the baud rate is 115200 for Zynq, and 9600 for Microblaze (when using the AXI Uartlite IP). If desired, other terminals, such as Tera Term or PuTTY, may be used instead. 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:connect-serial.png?600 |}} 
 +</WRAP> </WRAP>
  
 ---- ----
-=== 15. === 
  
-Program the FPGA by selecting **Xilinx -> Program FPGA** from the top menu bar. 
  
----- +<WRAP GROUP> <WRAP COLUMN HALF> 
-=== 16. ===+=== 6. === 
 +Program the FPGA by selecting **Xilinx -> Program FPGA** from the top menu bar in Xilinx SDK.
  
-Run the application project by right-clicking on the application project and selecting **Run -> Run on Hardware (System Debugger)**.+Once the FPGA is programmed, run the application project by right-clicking on the application project and selecting **Run -> Run on Hardware (System Debugger)**. 
 + 
 +Messages printed by the demo application can be seen in the serial terminal. 
 +</WRAP> <WRAP COLUMN HALF> 
 +{{ :learn:programmable-logic:tutorials:vivado-hierarchical-blocks:run-app.png?600 |}} 
 +</WRAP> </WRAP>
  
 ---- ----
 +===== Next Steps =====
 +Now that the hierarchical block's example design is running, modifications can easily be made to the hardware or software.
 +
 +The SDK sources provided with the hierarchical blocks are set up such that they can be easily included in any design using that block. The subfolder below sdk_sources contains all necessary drivers for the block.
 +
 +For more reference materials and guides on the Digilent products being used, navigate to their resource centers, here on the [[start:|Digilent Wiki]].
 +
 +For technical support, please visit the [[https://forum.digilentinc.com|Digilent Forums]].
 +
 {{tag>vivado-hierarchical-blocks}} {{tag>vivado-hierarchical-blocks}}