Creating an SDSoC Application

The first task is to identify portions of application code that are suitable for implementation in hardware, and that significantly improve the overall application performance when run in hardware.

Before marking any functions for acceleration you should profile the software. Self-contained compute intensive functions with limited external control logic are good starting points, especially when its possible to stream data between hardware, the CPU, and memory to overlap the computation with the communication. You can build and run your application on one of the platforms provided in the SDSoC environment install to identify compute intensive functions on the Arm processor.

Every base platform included in the SDSoC environment includes a pre-built SD card image from which you can boot and run your application code if you do not have any functions selected for acceleration on the hardware platform. Running the application this way enables you to profile the original application code to identify candidates for acceleration.

See Profiling and Optimization for more information on profiling your application. Also, the SDSoC Environment Profiling and Optimization Guide (UG1235) provides more extensive detail.

After determining the function or functions to move into hardware, with a project, you can select the function from the Add Hardware Functions portion of the window.

Click the Hardware Functions button of the Project Editor window to display the list of candidate functions within your program. This displays the Add Hardware Functions dialog box, that lets you select one or more functions from a list of functions in the call graph of the main function by default.

Figure: Add Hardware Functions Dialog Box

From within the Add Hardware Functions dialog box, select one or more functions for hardware acceleration and click OK.

The list of functions starts at the Root function as defined in the Options panel of the Project window and is set to main by default. You can change the Root function by clicking the Browse () command and selecting an alternate root.

The functions display in the Hardware Functions panel of the SDx Application Project Settings window as shown in the following figure.

Figure: Hardware Function Panel

When moving a function optimized for CPU execution into programmable logic, you can usually revise the code to improve the overall performance. See the "Programming Hardware Functions" section in the SDSoC Environment Programmers Guide (UG1278).

For accelerators using the xfOpenCV library, right-click and select Toggle Hardware from the associated header files in the project included in Project Explorer. See the Xilinx OpenCV User Guide for more information.

After selecting hardware functions, it could be necessary to select the clock frequency for running the function or the data motion network clock.

Every platform supports one or more clock sources, which is defined by the platform developer as described in SDSoC Environment Platform Development Guide. Setting the clock frequency of the hardware function determines the clock setting for the hardware function's logic as well as its associated data mover. Setting the clock frequency of the Data Motion network determines the clock used for the axi_lite control buses. By default, the Data Motion network shares its clock with the hardware accelerator generated during system generation. You can select the Data Motion network clock and the hardware function clock from the SDx IDE or the command line.

You can view the available platform clocks by selecting the Platform link in the General option of the SDx Application Project Settings window. This displays details of the platform, including the available clock frequencies.

Figure: SDx IDE – General

The function clock displays in the SDx Application Project Settings window, in the Hardware Functions panel.

Select a function from the list, like madd in the figure below, and click in the Clock Frequency column to access the pull-down menu to specify the clock frequency for the function.

Figure: Select Function Clock Frequency

To specify the Data Motion clock frequency, select the Data motion network clock frequency pull-down menu in the Options panel of the SDx Application Project Settings window. The Data Motion network clock frequency menu is populated by the available clocks on the platform.

Figure: Data Motion Network Clock Frequency

$ sds++ -c mmult.cpp -o mmult.o -sds-pf zcu102 -sds-hw mmult mmult.cpp -clkid 1 -sds-end

$ sds++ -lmyIpLib -ac myAc:3 -o main.elf main.o

$ sds++ -sds-pf zcu102 -dmclkid 1

$ sds++ -sds-pf-info <platform_name>

Platform Information
====================
Name: zcu102

Device
------
 Architecture: zynquplus
       Device: xczu9eg
      Package: ffvb1156
  Speed grade: -2

System Clocks
-------------
  Clock ID   Frequency
 ----------|------------
            1199.880127
         0    74.992500
         1    99.990000
         2   149.985000
         3   199.980000
         4   299.970000
         5   399.960000
         6   599.940000

Platform:    zcu102 (<SDx_Install_Dir>/platforms/zcu102)

Description: 
A basic platform targeting the ZCU102 evaluation board, which includes
4GB of DDR4 for the Processing System, 512MB of DDR4 for the Programmable
Logic, 2x64MB Quad-SPI Flash and an SDIO card interface. More information
at https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html
    
Available system configurations:
  a53_linux (a53_linux)
  a53_standalone (a53_standalone)
  r5_standalone (r5_standalone)
 
System Ports
 
Use the system port name in a sysport pragma, for example 
#pragma SDS data sysport(parameter_name:system_port_name)
 
System Port Name (Vivado BD instance name, Vivado BD port name)
ps_e_S_AXI_HPC0_FPD (ps_e, S_AXI_HPC0_FPD)
ps_e_S_AXI_HPC1_FPD (ps_e, S_AXI_HPC1_FPD)
ps_e_S_AXI_HP0_FPD (ps_e, S_AXI_HP0_FPD)
ps_e_S_AXI_HP1_FPD (ps_e, S_AXI_HP1_FPD)
ps_e_S_AXI_HP2_FPD (ps_e, S_AXI_HP2_FPD)
ps_e_S_AXI_HP3_FPD (ps_e, S_AXI_HP3_FPD)

1. Select the Build button () or right-click the project name and select Build Project in the Project Explorer window.
2. Initiate a build through the Assistant window by right-clicking either the Debug [Hardware] or Release [Hardware] selections.
3. Right-click Debug [Hardware] and, from the context menu, select Build.

   Figure: Assistant Window

   

   This generates a bitstream and bootable SD card image, based on the check-marked project options. The build process also produces a Compilation Log file and a Data Motion Network Report that you can access through the Assistant window.

4. The results of the build process produce files to populate an SD card for booting and running on a target board. Using the Assistant window, the set of generated files can be viewed by right-clicking and selecting SD Card Image > Open > Open in File Browser.

   Figure: Build Results

   

5. SDx creates detailed reports of the compilation process and saves those files in the Debug/_sds/reports directory. Access these files through the Project Explorer or the Assistant window. The following figure shows a Project Explorer expansion of the reports directory and a view into the sds.log compilation log file.

   Figure: Compilation Log

   

An excerpt of a log file showing the equivalent system compiler commands run by the IDE for creating the accelerators added as part of the matrix multiply and matrix add example, shown in the following code snippet. The -sds-pf option identifies the platform, and each accelerated function is identified by placing the function name and its defining source file between their own set of -sds-hw and -sds-end hardware function options. The accelerator clock ID is also chosen within the hardware function options by setting the -clkid option.

Compilation of function madd():

sds++ -Wall -O0 -g -I../src -c -fmessage-length=0 -MTsrc/madd.o\
 -MMD -MP -MFsrc/madd.d -MTsrc/madd.o -o src/madd.o ../src/madd.cpp\
 -sds-hw mmult mmult.cpp  -clkid 1 -sds-end\
 -sds-hw madd madd.cpp  -clkid 1 -sds-end\
 -sds-sys-config a53_linux -sds-proc a53_linux -sds-pf zcu102

Compilation of function main():

sds++ -Wall -O0 -g -I ../src -c -fmessage-length=0 -MTsrc/main.o\
 -MMD -MP -MFsrc/main.d -MTsrc/main.o -o src/main.o ../src/main.cpp\
 -sds-hw mmult mmult.cpp  -clkid 1 -sds-end\
 -sds-hw madd madd.cpp  -clkid 1 -sds-end\
 -sds-sys-config a53_linux -sds-proc a53_linux -sds-pf zcu102

Compilation of function mmult():

sds++ -Wall -O0 -g -I../src -c -fmessage-length=0 -MTsrc/mmult.o\ 
 -MMD -MP -MFsrc/mmult.d -MTsrc/mmult.o -o src/mmult.o ../src/mmult.cpp\ 
 -sds-hw mmult mmult.cpp -clkid 1 -sds-end\ 
 -sds-hw madd madd.cpp -clkid 1 -sds-end\ 
 -sds-sys-config a53_linux -sds-proc a53_linux -sds-pf zcu102

The compiled object files are then linked by the SDx tools to produce the single executable file for the matrix multiply and matrix add example containing the application code as well as the code to invoke the accelerated functions. This executable is targeted for Linux as specified with the -sds-sys-config and -sds-proc options.

Linking object files to produce an executable file (ELF) and boot files for SD card:

sds++ --remote_ip_cache /tmp/sdx_workspace/ip_cache -o project_one.elf\
 ./src/madd.o ./src/main.o ./src/mmult.o\
 -dmclkid 1 -sds-sys-config a53_linux\
 -sds-proc a53_linux -sds-pf zcu102

sds++ <command_options> -xp "vivado_prop:run.synth_1.STEPS.SYNTH_DESIGN.TCL.POST=<full path to postsynth.tcl>"

sds++ <command_options> -synth-strategy <strategy_name>

sds++ <command_options> -impl-strategy <strategy_name>

sds++ <command_options> -synth-strategy <strategy_name> -impl-strategy <strategy_name>

After the hardware functions are identified, the logic can be compiled, and the entire system (PS and PL) verified using emulation on Xilinx base platforms (such as zc702, zc706, zcu102, zcu104, and zcu106). System emulation allows you to verify and debug the system with the same level of accuracy as a full bitstream compilation, without requiring a bitstream. This can significantly reduce design iteration time, and allow faster iteration through debug cycles more.

To enable system emulation, from the Editor Area, click the Target field, and select Emulation.

Figure: Emulation Target

System emulation offers Debug and Optimized modes, which can be specified by clicking in the Emulation Model field.

Debug

Builds the system through RTL generation, and the Vivado IP integrator block design containing the hardware function, elaborates the hardware design, and runs behavioral simulation on the design, with a waveform viewer to help you analyze the results. If there is a functional issue with the code, use this option.

Optimized

Runs the behavioral simulation in batch mode, returning the results without the waveform data. While Optimized can be faster, it returns less information than Debug mode.

To capture waveform data from the PL hardware emulation for viewing and debugging, select the Debug pull-down menu option. For faster emulation without capturing this hardware debug information, select Optimized.

After specifying the emulation options, click the Build () command to compile the active build configuration. The Build command invokes the system compilers to build your application project. There are two build configurations available:

Debug

This compiles the project use in software debug. The compiler produces extra information for use by a debugger to facilitate debug and allows you to step through the code.

Release

The compiler tries to reduce code size and execution time of the application. This strips out the debug code so that you really cannot debug with this version.

You can launch the build from the Assistant window also, by selecting Debug[Emulation] > Build.

After system emulation has completed, the Assistant lists the Data Motion Network Report and the Compilation Log as shown in the following figure:

Figure: Assistant Window Display

The build process for hardware emulation can take some time, depending on your application code, the size of your hardware functions, and the various options you have selected. To compile the hardware functions, the tool stack includes SDx, Vivado HLS, and the Vivado Simulator.

After the system is compiled for emulation, you can invoke the system emulator using the Xilinx > Start/Stop Emulator menu command or using sdsoc_emulator from the command line.

When the Start/Stop Emulator dialog box opens, if the specified emulation mode is Debug, you can choose to run emulation with or without waveforms. If the emulation mode is Optimized, the Show waveforms check-box is disabled and cannot be changed.

Figure: Start/Stop Emulator

Disabling the Show Waveform option allows you to run emulation with the output directed solely at the Emulation Console view, which shows all system messages including the results of any print statements in the source code. Some of these statements might include the values transferred to and from the hardware functions, or a statement that the application has completed successfully, which would verify that the source code running on the PL and the compiled hardware functions running in the PS are functionally correct.

Enabling the Show Waveform option provides the same functionality in the console window, plus the behavioral simulation of the PL-resident IP with a waveform window in the Xsim tool. The waveform window allows you to see the value of any signal in the hardware functions over time.

When using Show Waveform, you must manually add signals to the waveform window before starting the emulation. Use the Scopes pane to navigate the design hierarchy, then select the signals to monitor in the Object pane, and right-click to add the signals to the waveform pane. Select the Run > Run All option to start updates to the waveform window. For more information on working with the Vivado simulator waveform window, see the Vivado Design Suite User Guide: Logic Simulation (UG900).

The system emulation can also be started by selecting the active project in the Project Explorer view and right-clicking to select Run As > Launch on Emulator menu command, or the Debug As > Launch on Emulator menu command. Launching the emulator from the Debug As menu prompts you to change to the debug perspective to arrange the windows and views to facilitate debugging the project. See Understanding the SDx GUI for more information on changing perspectives.

The program output is displayed in the console tab and if the Show Waveform option is selected, you also see any appropriate response in the hardware functions in the RTL-PL waveform. During any pause in the execution of the code, the RTL-PL waveform window continues to execute and update, just like an FPGA running on the board.

The emulation can be stopped at any time using the menu option Xilinx > Start/Stop Emulator and selecting Stop.

A system emulation session with the quick emulation (QEMU) console is shown in the following figure.

Figure: QEMU Console

As shown in the following figure, the PL waveform displays if you selected the waveform option and the Run All option:

Figure: Waveform Window

The Assistant window enables you to right-click Debug > Run > Launch on Emulator (SDx Application Debugger).

You can find more information about emulation in the SDSoC Environment Debugging Guide.

The shared library includes a Matrix Shared Library template with a multiply and add example provided with the SDx IDE. This library demonstrates how three different functions with unique entry points in the shared library can be called from a software application.

When running the results of an application build invoked through the SDx IDE, the BOOT.BIN file in the sd_card directory of the library project should be used to boot the board as it contains the accelerated hardware functions.

For command line use, an example is available in the <SDx_Install_Dir>/samples/libmatrix directory. The libmatrix example contains makefiles that demonstrate how to build static and shared libraries as well as how to use the libraries with an application.

For more information on building a shared library, see the "Building a Shared Library" section in SDSoC Environment Programmers Guide (UG1278).