This document is an overview of the IP Integrator examples provided through the HLx environment.
Prior to starting you should have completed Vivado Setup Instructions to help setup and get familar with the Vivado GUI and IP Integrator.
All of the examples have been integrated into an automated flow that automatically generates the Vivado project.
This section covers IP Integrator example designs that can help you get familar with the automated project generation flow and IP Integrator.
Current examples include the following:
Select the above link for detailed information on the design and how to get started with using that design.
The following CL examples cover using an automated RTL example design with Vivado. The examples are based on the HDK cl/examples directory (ex: cl_hello_world and cl_dram_dma).
Current examples include the following:
Select the above link for detailed information on the design and how to get started with using that design.
The IPI example turtorial will cover how to configure the AWS IP with the BAR1 Interface (AXI4-Lite Master Interface) and the PCIS Interface (AXI4 Master).
The AXI GPIO IP is added to the design to control the VLED. Also, the AXI BRAM is added to the design for the PCIS Interface (AXI4 Master).
The VLED is set based upon writing 0xAAAA into the AXI GPIO (0x0) slave register to drive VLED. The value is read using the Verilog task tb.get_virtual_led or fpga-get-virtual-led on F1.
The PCIS Interfaces writes ASCII data into the AXI BRAM memory space and reads back from these address to print out “Hello World!” in simulation or on F1.
Change directories to hdk/cl/examples
Create a directory in examples like hello_world_vivado
Change directories into hello_world_vivado/
Start Vivado by typing vivado in the bash console.
Create a project any device by typing the following command in Vivado's TCL Tab.
create_project -name hello_world
Type in the following TCL command which changes the project settings for AWS and creates the block diagram with the AWS IP added.
aws::make_ipi
Double click on the AWS IP block. Under IP Interfaces select Use BAR1 Register Interface (M_AXI_BAR1), Use PCI Slave-access Interface (M_AXI_PCIS), and Use Auxiliary (non-AXI) Signal Ports. This enables the AXI4-Lite Master Interface (for AXI GPIO), AXI4 Master Interface (for AXI BRAM) and the VLED/VDIP input/outputs. Select OK.
The AWS IP is configured for one clock using the Group-A Clock with the default clock recipe which configures a 125 MHz clock.
Right click in the canvas and select Add IP... Search for AXI GPIO and double click on AXI GPIO.
In the canvas for axi_gpio_0, double click on the block to configure the IP.
In the Re-customize IP Dialog Box, under the GPIO section select All Outputs and GPIO Width of 16. Select OK.
Right click in the canvas, and select Add IP... Search for AXI BRAM and double click on AXI BRAM Controller.
In the canvas for axi_bram_ctrl_0, double click on the block to configure the IP.
Set the Data Width to 512 and click OK. This is to match the 512-bit data width of the PCIS AXI4 Master Interface.
Select Run Connection Automation at the top of the Block Diagram in the green highlighted section.
Select axi_bram_ctrl_0/BRAM_PORTA and then BRAM_PORTB and select Auto. For axi_bram_ctrl_0/S_AXI, make sure Master is set to /f1_inst/M_AXI_PCIS and the rest of the options are Auto.
Select axi_gpio_0/S_AXI. Make sure Master is set to /f1_inst/M_AXI_BAR1 and the rest of the options are Auto.
The axi_gpio_0/GPIO will be manually configured after Run Connection Automation.
Select OK.
Expand axi_gpio_0/GPIO by select the +. Connect gpio_io_o[15:0] on the f1_inst block and make a connection to status_vled[15:0] and Run Connection Automation.
Select the Address Editor tab on top of the block diagram.
The AXI BRAM instance is configured with 64K address space by default starting at address 0xC0000000. The address space can be increased or decreased by selecting a different value for Range.
The AXI GPIO instance has a 4K address space which is reflected in the addressing for M_AXI_BAR1 which starts at 0x00000000.
Save the block diagram and select Tools->Validate Design.
Select OK Once Validation is successful.
In the Flow Navigator tab/Project Manager select Add Sources -> Add or create simulation sources -> Select Add Files.
Add the hdk/common/shell_stable/hlx/hlx_examples/build/IPI/hello_world/verif/test_cl.sv
Deselect Scan and add RTL includes files into project
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy sources into project to link to the source files.
Select Add sources from subdirectories.
Select Include all design sources for simulation. Then click Finish.
Right click on SIMULATION in the Project Manager and select Simulation Settings…
For Verilog options select the … box and change the following names (should already be configured).
CL_NAME=cl_top
TEST_NAME=test_cl
Click OK, Click Apply, Click OK to go back into the Vivado project.
Select Simulation->Run Simulation->Run Behavioral Simulation from the Flow Navigator Tab.
Add signals needed in the simulation.
Type in the following in the TCL console. Note if Critical Warnings appear click OK and the following command needs to run two times. This is a known issue and will be addressed in later versions of the design.
run -all
No additional constraints are needed for this design.
Right click on impl_1 and select Launch Runs… and Click OK.
Click OK on the Missing Synthesis Results Dialog Box.
This will run both synthesis and implementation.
The completed .tar file is located in .runs/faas_1/build/checkpoints/to_aws/.Developer_CL.tar. For information on how to create a AFI/GAFI with .tar from the design, following to the How To Create an Amazon FPGA Image (AFI) From One of The CL Examples: Step-by-Step Guide documentation.
The runtime software must be compiled for the AFI to run on F1.
Copy the software directory to any directory and compile with the following commands.
$ cp -r $HDK_COMMON_DIR/shell_stable/hlx/hlx_examples/build/IPI/hello_world/software
$ cd software
$ make all
$ sudo ./test_cl
The hello_world example demonstrates basic Shell-to-CL connectivity, memory-mapped register instantiations and the use of the Virtual LED and DIP switches. The hello_world example implements two registers in the FPGA AppPF BAR0 memory space connected to the OCL AXI-L interface. The two registers are:
- Hello World Register (offset 0x500)
- Virtual LED Register (offset 0x504)
The logic for the original cl_hello_world example from github is contained in one RTL module (hello_world.v). In hello_world.v, the top level ports are for AXI4-Lite interface, clock/reset and ports for VLED and VDIP which allows for IP packaging of the design and reuse with other flows/AXI4-Lite Master interfaces. Note VIO logic is not included with this example from the original hello_world.
Change directories to hdk/cl/examples
Create a directory in examples like cl_hello_world_ref_vivado
Change directories into cl_hello_world_ref_vivado/
Start Vivado by typing vivado in the console.
Create a project any device with the following command.
create_project -name cl_hello_world_ref
Type in the following command which changes the project settings for AWS and creates the block diagram with the AWS IP added.
aws::make_ipi
In Flow Navigator->Under Project Manager select Add Sources. Select Add or create design sources and select Add Directories.
Add the hdk/common/shell_stable/hlx/hlx_examples/build/IPI/cl_hello_world_ref/design directory.
Add the cl/examples/common/design directory.
Select Scan and add RTL includes files into project
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy sources into project to link to the source files.
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy sources into project to add the source files to local Vivado project.
Select Add sources from subdirectories.
Double click on the AWS IP. Under IP Interfaces select Use OCL Register Interface and Use Auxiliary (non-AXI) Signal Ports. This enables the AXI4-Lite Master Interface and the VLED/VDIP input/outputs.
Select Run Connecting Automation on the top of the Block Diagram. Select AUTO for Crossbar clock source of Interconnect IP/Clock source for Master interface/Clock source for Slave interface. The default clock is the 125 MHz coming from clk_main_a0_out from the f1_inst.
Address spaces is configured as the default which the whole address space of OCL. This can be changed in Address Editor for a smaller address space if necessary.
Select vled pin and connect to status_vled on the f1_inst block.
Select status_vdip on the f1_inst block and make a connection to vdip.
Right click on the connection between M_AXI_OCL on f1_inst and S00_AXI on f1_inst_axi_periph and select Debug.
Click on Run Connection Automation and click on for System ILA to be added to the design. If necessary the AXI-MM Protocol Checker can be selected when debugging new IPs.
Save the block diagram and select Tools->Validate Design.
Select OK Once Validation is successful.
Add or create simulation sources. Select Add Files.
Add the cl/examples/cl_hello_world/verif/tests/test_hello_world.sv
Deselect Scan and add RTL includes files into project
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy sources into project to link to the source files.
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy sources into project to add the source files to local Vivado project.
Select Add sources from subdirectories.
Select all design sources for simulation.
Right click on SIMULATION in the Project Manager and select Simulation Settings…
For Verilog options select the … box and change the following names.
CL_NAME=cl_top
TEST_NAME=test_hello_world
Click OK, Click Apply, Click OK to back into the Vivado project.
Select Simulation->Run Simulation->Run Behavioral Simulation from the Flow Navigator Tab.
Add signals needed in the simulation.
Type in the following in the TCL console. Note if Critical Warnings appear click OK and that the following command needs to ran two times. This is a known issue and will be addressed in later versions of the design.
run -all
No additional constraints are needed for this design.
Right click on impl_1 and select Launch Runs… and Click OK.
Click OK on the Missing Synthesis Results Dialog Box.
This will run both synthesis and implementation.
The completed .tar file is located in .runs/faas_1/build/checkpoints/to_aws/.Developer_CL.tar. For information on how to create a AFI/GAFI with .tar from the design, following to the How To Create an Amazon FPGA Image (AFI) From One of The CL Examples: Step-by-Step Guide documentation.
The runtime software must be complied for the AFI to run on F1.
Use the software in cl/examples/cl_hello_world
$ cd cl/cl_hello_world/software/runtime/
$ make all
$ sudo ./test_hello_world
This example shows how to add existing RTL, simulation RTL, and constraints into a Vivado project. This example uses cl_hello_world from the github examples directory.
Change directories to hdk/cl/examples
Create a directory in examples like cl_hello_world_vivado
Change directories into cl_hello_world_vivado/
For the clock recipes and IDs set the following system variables (these match cl_hello_world example).
export CLOCK_A_RECIPE=0
export CLOCK_B_RECIPE=0
export CLOCK_C_RECIPE=0
export device_id=0xF000
export vendor_id=0x1D0F
export subsystem_id=0x1D51
export subsystem_vendor_id=0xFEDD
Start Vivado by typing vivado in the console.
Type in the following to create a generic project.
create_project -name cl_hello_world
To setup the project for RTL mode, type in the following command.
aws::make_rtl
In Flow Navigator->Under Project Manager select Add Sources. Select Add or create design sources and select Add Directories.
Add the cl/examples/cl_hello_world/design directory.
Add the cl/examples/common/design directory.
Select Scan and add RTL includes files into project
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy sources into project to link to the source files.
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy sources into project to add the source files to local Vivado project.
Select Add sources from subdirectories.
Add or create simulation sources. Select Add Files. Add the <cl_dir>/verif/tests/test_hello_world.sv
Deselect Scan and add RTL includes files into project
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy sources into project to link to the source files.
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy sources into project to add the source files to local Vivado project.
Select Add sources from subdirectories.
Select all design sources for simulation.
Right click on SIMULATION in the Project Manager and select Simulation Settings…
For Verilog options select the … box and change the following names.
CL_NAME=cl_hello_world
TEST_NAME=test_hello_world
Click OK, Click Apply, Click OK to back into the Vivado project.
Select Simulation->Run Simulation->Run Behavioral Simulation from the Flow Navigator Tab.
Add signals needed in the simulation.
Type in the following in the TCL console.
run -all
Constraints can be copied and pasted from opening the original XDCs in a text editor and copying the constraints into the project .xdc files.
For cl_hello_world, copy the following into the cl_pnr_user.xdc in the Source->Constraints->cl_pnr_user.xdc. Note this is only for cl_hello_world.
set_false_path -from [get_cells CL/vled_q_reg*]
Overriding the .xdc in the Vivado project.
cl_synth_user.xdc/cl_pnr_user.xdc can be copied over from the /build/constraints area to the imported area of the Vivado project like the following.
<example_design>/build/constraints/ to <project_name>.srcs/constrs_1/imports/subscripts
Deleting the existing .xdc in the Vivado project and import constraints or copy constraints into Vivado project.
Delete cl_synth_user.xdc and cl_pnr_user.xdc in the Source->Constraints tab.
In Flow Navigator select Add Sources and select Add or create constraints.
For cl_synth_user.xdc and cl_pnr_user.xdc select the minus (-) button. Select Add Files and go to the hdk/cl/examples/<cl_example>/build/constraints directory. Select cl_pnr_user.xdc and cl_synth_user.xdc.
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy constraints files into project to link to the source files.
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy constraints files into project to add the source files to local Vivado project.
In the Sources/Hierarchy Tab, select cl_pnr_user.xdc and go to Source File Properties. Under the General Tab, deselect Enabled and select Implementation Box only. In Properties Tab, select PROCESSING_ORDER to be LATE.
Right click on impl_1 and select Launch Runs… and Click OK.
Click OK on the Missing Synthesis Results Dialog Box.
This will run both synthesis and implementation.
The completed .tar file is located in .runs/faas_1/build/checkpoints/to_aws/.Developer_CL.tar. For information on how to create a AFI/GAFI with .tar from the design, following to the How To Create an Amazon FPGA Image (AFI) From One of The CL Examples: Step-by-Step Guide documentation.
The runtime software must be complied for the AFI to run on F1.
Use the software in cl/examples/cl_hello_world
$ cd cl/cl_hello_world/software/runtime/
$ make all
$ sudo ./test_hello_world
This example shows how to add existing RTL, simulation RTL, and constraints into a Vivado project. This example uses cl_dram_dma from the github examples directory.
Make sure the HLx Setup Instructions are followed before continuing.
Change directories to hdk/cl/examples
Create a directory in examples like cl_dram_dma_vivado
Change directories into cl_dram_dma_vivado/
For the clock recipes and IDs set the following system variables (these match cl_dram_dma example).
export CLOCK_A_RECIPE=0
export CLOCK_B_RECIPE=0
export CLOCK_C_RECIPE=0
export device_id=0xF001
export vendor_id=0x1D0F
export subsystem_id=0x1D51
export subsystem_vendor_id=0xFEDC
Start Vivado by typing vivado in the console.
Type in the following to create a generic project.
create_project -name cl_dram_dma
To setup the project for RTL mode, type in the following command.
aws::make_rtl
In Flow Navigator->Under Project Manager select Add Sources. Select Add or create design sources and select Add Directories.
Add the cl/examples/cl_dram_dma/design directory.
Add the cl/examples/common/design directory.
Select Scan and add RTL includes files into project
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy sources into project to link to the source files.
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy sources into project to add the source files to local Vivado project.
Select Add sources from subdirectories.
cl_dram_dma example has several system verilog tests (test_ddr.sv, test_dram_dma.sv, test_ini.sv, test_peek_poke.sv, test_peek_poke_pcis_axsize.sv).
Add or create simulation sources. Select Add Files and individually add in the .sv files needed.
Add the <cl_dir>/verif/tests/<tests_to_add>.sv
Deselect Scan and add RTL includes files into project
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy sources into project to link to the source files.
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy sources into project to add the source files to local Vivado project.
Select Add sources from subdirectories.
Select all design sources for simulation.
Right click on SIMULATION in the Project Manager and select Simulation Settings…
For Verilog options select the … box and change the following names.
CL_NAME=cl_dram_dma
For TEST_NAME choose the name of the .sv used (don’t put .sv at the end of the line).
Below is an example.
TEST_NAME=test_dram_dma
Click OK, Click Apply, Click OK to back into the Vivado project.
Select Simulation->Run Simulation->Run Behavioral Simulation from the Flow Navigator Tab.
Add signals needed in the simulation.
Type in the following in the TCL console.
run -all
Constraints can be copied and pasted from opening the original XDCs in a text editor and copying the constraints into the project .xdc files.
Overriding the .xdc in the Vivado project.
cl_synth_user.xdc/cl_pnr_user.xdc can be copied over from the /build/constraints area to the imported area of the Vivado project like the following.
<example_design>/build/constraints/ to <project_name>.srcs/constrs_1/imports/subscripts
Deleting the existing .xdc in the Vivado project and import constraints or copy constraints into Vivado project.
Delete cl_synth_user.xdc and cl_pnr_user.xdc in the Source->Constraints tab.
In Flow Navigator select Add Sources and select Add or create constraints.
For cl_synth_user.xdc and cl_pnr_user.xdc select the minus (-) button.
Select Add Files and go to the hdk/cl/examples/<cl_example>/build/constraints directory.
Select cl_pnr_user.xdc and cl_synth_user.xdc.
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy constraints files into project to link to the source files.
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy constraints files into project to add the source files to local Vivado project.
In the Sources/Hierarchy Tab, select cl_pnr_user.xdc and go to Source File Properties. Under the General Tab, deselect Enabled and select Implementation Box only. In Properties Tab, select PROCESSING_ORDER to be LATE.
Right click on impl_1 and select Launch Runs… and Click OK.
Click OK on the Missing Synthesis Results Dialog Box.
This will run both synthesis and implementation.
The runtime software must be complied for the AFI to run on F1. Note the EDMA driver must be installed before running on F1.
Use the software in cl/examples/cl_dram_dma
$ cd cl/cl_dram_dma/software/runtime/
$ make all
$ sudo ./test_dram_dma
This example shows how to add existing RTL, simulation RTL, and constraints into a Vivado project based upon template files provided from github.
Make sure the HLx Setup Instructions are followed before continuing.
Change directories to hdk/cl/examples
Create a directory in examples like cl_template or the proposed design name.
Change directories into cl_template/
For the clock recipes and IDs set the following system variables which are defaults. These values can be changed later either in the bash shell or in Vivado based upon the design's needs.
export CLOCK_A_RECIPE=0
export CLOCK_B_RECIPE=0
export CLOCK_C_RECIPE=0
export device_id=0xF000
export vendor_id=0x1D0F
export subsystem_id=0x1D51
export subsystem_vendor_id=0xFEDD
Start Vivado by typing vivado in the console.
Type in the following to create a generic project (change the project name to the proposed design name).
create_project -name cl_template
aws::make_rtl
In Flow Navigator->Under Project Manager select Add Sources. Select Add or create design sources and select Add Directories.
Add the hdk/common/shell_stable/new_cl_template/design directory.
Select Scan and add RTL includes files into project
Select Copy sources into project to add the source files to local Vivado project. The templates are stored in the local Vivado project and can be modified in Vivado or a text editor.
Select Add sources from subdirectories.
cl_template_defines.vh – Verilog header file where user puts in generic `define based upon the design.
cl_template.sv – Top level file where user adds in logic, modules and `include .inc files to disable interfaces not used in the shell.
If certain shell interfaces are not enabled, the user needs to use the .inc provided in HDK to disable the interface in cl_template.sv. See the example designs for examples on using these .inc files.
In Flow Navigator->Under Project Manager select Add Sources. Select Add or create design sources and select Add Directories.
Add the directories or files needed.
Select Scan and add RTL includes files into project
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy sources into project to link to the source files.
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy sources into project to add the source files to local Vivado project.
To add new IP to the design, select IP Catalog, find the particular IP and configure, and generate with Global synthesis mode (Out of Context is not supported at this time). The template .vho/.veo can be used to insert the IP into the RTL.
To import IP do the following.
In Flow Navigator->Under Project Manager select Add Sources. Select Add or create design sources.
Add the XCI file of the IP or IPs. Make sure to generate with Global synthesis mode (Out of Context is not supported at this time).
Import Only - Sources are not copied to the Vivado project and pointed to outside of the Vivado project.
Deselect Copy sources into project to link to the source files.
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy sources into project to add the source files to local Vivado project.
Simulation/system behavior should be verified before attempting the implementation flows.
In the Flow Navigator tab/Project Manager select Add Sources. Add or create simulation sources. Select Add Files.
Add the hdk/common/shell_stable/hlx/hlx_examples/verif/test_cl.sv
Deselect Scan and add RTL includes files into project
Copy to Project - Sources are copied to the Vivado project where the user can modify the sources without impact to the original sources.
Select Copy sources into project to add the source files to local Vivado project.
Select Add sources from subdirectories.
Select Include all design sources for simulation. Then click Finish.
Right click on SIMULATION in the Project Manager and select Simulation Settings…
For Verilog options select the … box and change the following names (should all ready be configured).
CL_NAME=cl_top
TEST_NAME=test_cl
Click OK, Click Apply, Click OK to back into the Vivado project.
Modify test_cl.sv based upon interfaces used in the design. Examples are provided in test_cl.sv for a majority of the interfaces.
Select Simulation->Run Simulation->Run Behavioral Simulation from the Flow Navigator Tab.
Add signals needed in the simulation.
Type in the following in the TCL console. Note if Critical Warnings appear click OK and that the following command needs to ran two times. This is a known issue and will be addressed in later versions of the design.
run -all
The following files are added to the Vivado project automatically.
cl_clocks_aws.xdc – Top level clock constraints for the CL. This file should not be touched as it's dynamically created during the synthesis process.
cl_synth_aws.xdc - Timing constraints between sh_ddr module and DDR4 IP. This file should be disabled in the Vivado project if no DDR4 instances are in the CL.
cl_synth_user.xdc – User can modify this file for the the CL for synthesis (I.E creating new clock structures with clock generator/using clocks in different Shell MMCM).
cl_pnr_user.xdc – User can modify this file for constraints between the CL/SH for implementation(place/route). Floorplanning is done in this file if necessary.
Right click on impl_1 and select Launch Runs… and Click OK.
Click OK on the Missing Synthesis Results Dialog Box.
This will run both synthesis and implementation.