|
| 1 | +Hardware Debug of Vitis Kernel |
| 2 | +====================== |
| 3 | + |
| 4 | +This file contains the following sections: |
| 5 | + |
| 6 | +1. Overview |
| 7 | +2. Enabling ChipScope Debug |
| 8 | +3. Host code changes to support debugging |
| 9 | +4. Building the executable, creating the AFI, and executing the host code |
| 10 | +5. Start debug servers |
| 11 | + |
| 12 | + |
| 13 | +## 1. Overview |
| 14 | +The sections below give you a brief explanation of the steps required to debug your Vitis kernel. They include enabling ChipScope debug, pausing the execution of the host code at the appropriate stage to ensure the setup of ILA triggers, building the running the host code and starting the debug servers to debug the design in hardware. |
| 15 | + |
| 16 | +## 2. Enabling ChipScope Debug |
| 17 | + |
| 18 | +Debug cores can be added to the AXI interfaces on the kernel itself to monitor AXI transaction level activity (part of the ChipScope Debug feature of Vitis). |
| 19 | + |
| 20 | +Adding debug cores to the AXI interfaces on the kernel can be done using the v++ --dk chipscope option with the compute unit name and optional interface name. |
| 21 | + |
| 22 | +This can be enabled by adding an v++ option to the CLFLAGS in the makefile. The --dk option shown below shows the general usage: |
| 23 | + |
| 24 | +``` |
| 25 | +--dk chipscope:<compute_unit_name>:<interface_name> |
| 26 | +``` |
| 27 | + |
| 28 | +For example, to add ChipScope debugging to the helloworld_ocl OpenCL example , enabling chipscope debug can be accomplished by adding the following v++ option to the CLFLAGS in the makefile: |
| 29 | + |
| 30 | +``` |
| 31 | +--dk chipscope:krnl_vadd_1 |
| 32 | +``` |
| 33 | + |
| 34 | +For detailed usage and more examples, refer to the Debugging section of Vitis Application Acceleration (UG1393). |
| 35 | + |
| 36 | + |
| 37 | +### Adding debug cores to the RTL kernel code |
| 38 | + |
| 39 | +To debug signals internal to an RTL Kernel you need to instantiate debug cores like the Integrated Logic Analyzer(ILA), Virtual Input/Output(VIO) etc in your application RTL kernel code. |
| 40 | + |
| 41 | +The ILA Debug IP can be created and added to the RTL Kernel in a couple of ways. |
| 42 | + |
| 43 | + |
| 44 | +1. Open the ILA IP customization wizard in the Vivado GUI and customize the ILA and instantiate it in the RTL code – similar to any other IP in Vivado. |
| 45 | + |
| 46 | + |
| 47 | +2. Create the ILA IP on the fly using TCL. A snippet of the create_ip TCL command is shown below. The example below creates the ILA IP with 7 probes and associates properties with the IP. |
| 48 | + |
| 49 | +``` |
| 50 | +create_ip -name ila -vendor xilinx.com -library ip -module_name ila_0 |
| 51 | +set_property -dict [list CONFIG.C_PROBE6_WIDTH {32} CONFIG.C_PROBE3_WIDTH {64} |
| 52 | +CONFIG.C_NUM_OF_PROBES {7} CONFIG.C_EN_STRG_QUAL {1} CONFIG.C_INPUT_PIPE_STAGES {2} CONFIG.C_ADV_TRIGGER {true} CONFIG.ALL_PROBE_SAME_MU_CNT {4} CONFIG.C_PROBE6_MU_CNT {4} CONFIG.C_PROBE5_MU_CNT {4} CONFIG.C_PROBE4_MU_CNT {4} CONFIG.C_PROBE3_MU_CNT {4} CONFIG.C_PROBE2_MU_CNT {4} CONFIG.C_PROBE1_MU_CNT {4} CONFIG.C_PROBE0_MU_CNT {4}] [get_ips ila_0] |
| 53 | +``` |
| 54 | + |
| 55 | +This TCL file should be added as an RTL Kernel source in the Makefile of your design |
| 56 | + |
| 57 | + |
| 58 | +Now you are ready to instantiate the ILA Debug core in your RTL Kernel. The RTL code snippet below is an ILA that monitors the output of a combinatorial adder. |
| 59 | + |
| 60 | + // ILA monitoring combinatorial adder |
| 61 | + ila_0 i_ila_0 ( |
| 62 | + .clk(ap_clk), // input wire clk |
| 63 | + .probe0(areset), // input wire [0:0] probe0 |
| 64 | + .probe1(rd_fifo_tvalid_n), // input wire [0:0] probe1 |
| 65 | + .probe2(rd_fifo_tready), // input wire [0:0] probe2 |
| 66 | + .probe3(rd_fifo_tdata), // input wire [63:0] probe3 |
| 67 | + .probe4(adder_tvalid), // input wire [0:0] probe4 |
| 68 | + .probe5(adder_tready_n), // input wire [0:0] probe5 |
| 69 | + .probe6(adder_tdata) // input wire [31:0] probe6 |
| 70 | + ); |
| 71 | + |
| 72 | + |
| 73 | +## 3. Host code changes to support debugging |
| 74 | + |
| 75 | +The application host code needs to be modified to ensure you can set up the ILA trigger conditions **prior** to running the kernel. |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +The host code shown below introduces the wait for the setup of ILA Trigger conditions and the arming of the ILA. |
| 80 | + |
| 81 | +src/host.cpp |
| 82 | + |
| 83 | + void wait_for_enter(const std::string& msg) |
| 84 | + { |
| 85 | + std::cout << msg << std::endl; |
| 86 | + std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n'); |
| 87 | + } |
| 88 | + |
| 89 | + ... |
| 90 | + |
| 91 | + cl::Program::Binaries bins = xcl::import_binary_file(binaryFile); |
| 92 | + devices.resize(1); |
| 93 | + cl::Program program(context, devices, bins); |
| 94 | + cl::Kernel krnl_vadd(program,"krnl_vadd_rtl"); |
| 95 | + |
| 96 | + wait_for_enter("\nPress ENTER to continue after setting up ILA trigger..."); |
| 97 | + |
| 98 | + //Allocate Buffer in Global Memory |
| 99 | + |
| 100 | + ... |
| 101 | + |
| 102 | + //Launch the Kernel |
| 103 | + q.enqueueTask(krnl_vadd); |
| 104 | + |
| 105 | + |
| 106 | + |
| 107 | +## 4. Building the executable, creating the AFI and executing the host code |
| 108 | + |
| 109 | +- **Build the executable** in your design directory (`your_design_directory`) by running the steps below: |
| 110 | + |
| 111 | +``` |
| 112 | + cd your_design_directory |
| 113 | +
|
| 114 | + make all DEVICES=$AWS_PLATFORM |
| 115 | +``` |
| 116 | + |
| 117 | +- **Creating and registering the AFI** |
| 118 | + |
| 119 | +Please note, the angle bracket directories need to be replaced according to the user setup. |
| 120 | + |
| 121 | +``` |
| 122 | + $VITIS_DIR/tools/create_vitis_afi.sh -xclbin=your_design.xclbin -o=your_design.awsxclbin -s3_bucket=<bucket-s3_dcp_key=<f1-dcp-folder-s3_logs_key=<f1-logs> |
| 123 | +``` |
| 124 | + |
| 125 | +- **Setup and Execute** |
| 126 | + |
| 127 | +``` |
| 128 | + $ cd $AWS_FPGA_REPO_DIR |
| 129 | + $ source vitis_runtime_setup.sh |
| 130 | + $ ./host |
| 131 | +``` |
| 132 | +This produces the following output: |
| 133 | +``` |
| 134 | +
|
| 135 | + platform Name: Xilinx |
| 136 | + Vendor Name : Xilinx |
| 137 | + Found Platform |
| 138 | + XCLBIN File Name: vadd |
| 139 | + INFO: Importing ./binary_container_1.awsxclbin |
| 140 | + Loading: './binary_container_1.awsxclbin' |
| 141 | + Successfully skipped reloading of local image. |
| 142 | + |
| 143 | + Press ENTER to continue after setting up ILA trigger... |
| 144 | +``` |
| 145 | + |
| 146 | + |
| 147 | +## 5. Start Debug Servers |
| 148 | + |
| 149 | +#### Starting Debug Servers on Amazon F1 instance |
| 150 | +Instructions to start the debug servers on an Amazon F1 instance can be found [here](../../hdk/docs/Virtual_JTAG_XVC.md). |
| 151 | +Once you have setup your ILA triggers and armed the ILA core, you can now Press Enter on your host to continue execution of the application and RTL Kernel. |
| 152 | + |
0 commit comments