C-Callable IP Libraries

TheSDx™installation contains examples of C-Callable IP in the/samples/rtldirectory. These examples show single-function as well as multi-function accelerator libraries where function arguments are passed as registers, memory references, or AXI streams, which are highlighted (axilite_arraycopy,aximm_arraycopy,axis_arraycopy). The multi-function examples (mfa_fir,mfa_scalar128_none,mfa_scalar_axi) highlight single accelerators with multiple software entry points.

TheSDxIDE's Library Project flow is used to create a C-Callable IP library with foundational support from thesdx_packutility. A description of thesdx_packcommand line arguments can be found in theSDx Command and Utility Reference Guide(UG1279). For inspecting interfaces withinVivado-packaged IP,sdx_packprovides the capability to query IP settings including their hardware interfaces. TheSDxIDE uses this feature to populate menu selections with interfaces and pull-down choices relevant to the IP being transformed into a C-Callable IP library.

A procedure for creating a C-Callable IP library using theaxis_arraycopyexample for a zcu102 platform is described below. Theaxis_arraycopyexample contains theVivado-packaged IP and the files used to create thelibarraycopy.alibrary. Thearraycopy.hppheader file contains the software function declarations associated with the hardware functionality provided in the packaged IP. Thecomponent.xmlcontains the meta-data used by theSDxIDE and the underlyingsdx_packtool to build the library.

The following steps are necessary to create the C-Callable IP library with theSDxIDE:

1. Create a C-Callable IP Library project.
   • Each library is created for a specificdevice_family,cpu_type, andOS_typetuple.
2. Import source files from the/samples/rtldirectory.
   • Import both the header file and the packaged IP.
3. Identify the header file (.hpp) and the IP meta-data file (component.xml) to use as inputs to build the C-Callable IP library.
4. Show how to customize the IP.
5. Indicate how the arguments of each function in the C-Callable IP library maps to the hardware IP.

The following tables guide you on how to complete theSDxdialogs.

• The top row of each table contains theSDxIDE menu selection to begin each task.
• TheDialogcolumn lists the names of the subsequent dialog boxes that open.
• SelectionandActioncolumns indicate how to fill out the dialog boxes to complete the task.

After generating the C-Callable library, create a newSDxApplication project to use the library. Continuing with the example of theaxis_arraycopyC-Callable IP library built in the previous section, use the generated library (libarraycopy.a) from the library build's Release directory. The result of building the Application project is an executable file (ELF) that is linked with the C-Callable IP Library.

1. Create anSDxapplication project to output an executable file. ClickFile>New>SDx Application Project.
   Note:The tuple consisting of device_family, cpu_type, and os_typemust match that of the C-Callable IP library.

   Table 6.SDxApplication Project

   Dialog Box	Selection or Field Name	Action
   Project Type	Application	ClickNext
   Create a NewSDxProject	Project name:	app_arraycopy
   	Use default location	Check-marked
   		ClickNext
   Platform	Name	zcu102
   		ClickNext
   System Configuration	System configuration:	A53_Linux
   	Runtime:	C/C++
   	Domain:	a53_linux
   (pre-set)	CPU:	cortex-a53
   (pre-set)	OS:	linux
   	Linux Root File System:	Unchecked
   		ClickNext
   Templates	Empty Application	ClickFinish

2. Import the function declarations header file (.hpp) common to both the library and the application. In the Project Explorer window, right-clickapp_arraycopyand selectImport Sources.

   Table 7.Select Import Sources

   Dialog	Selection or Field Name	Action
   File system	From directory:	Browse toaxis_arraycopy/src directory in /samples/rtl.
   		ClickOK
   	Files: arraycopy.hpp	Check-marked
   	Into folder:	app_arraycopy/src
   		ClickFinish

3. Open the Importing Sources dialog box again to get the example main application code from the/samples/rtldirectory. In the Project Explorer window, right-clickapp_arraycopyand selectImport Sources.

   Table 8.Select Import Sources

   Dialog	Selection or Field Name	Action
   File system	From directory:	Browse to theaxis_arraycopy/appdirectory in/samples/rtl
   		ClickOK
   	Files: main.cpp	Check-marked
   	Into folder:	app_arraycopy/src
   		ClickFinish

   Now that the source files for theapp_arraycopyapplication have been imported, update theC/C++ Build Settingsto have thesds++linker use thearraycopy.aC-Callable IP library when building the application.
4. Update theC/C++ Build Settingsin the Project Explorer window, right-clickapp_arraycopyand selectC/C++ Build Settingsas shown in the table.

   Table 9.C/C++ Build Settings

   Dialog	Selection or Field Name	Action
   Settings>Tool Settings	SDS++ Linker	SelectLibraries
   		ClickAddsymbol (with "+" icon) in the Libraries (-l) window
   	Libraries(-l)	arraycopy
   		ClickOK
   		ClickAddsymbol (with "+" icon) in the Library search path (-L) window
   		ClickWorkspace
   	Folder:	Navigate to and selectarraycopy/Release
   		ClickOK
   (pre-set)	Directory:	${workspace_loc:/arraycopy/Release}
   		ClickOK
   		ClickApply and Close

To create the application, you can use the Assistant window to build theapp_arraycopyapplication.

1. In the Assistant window underapp_arraycopy[SDSoC], right-clickDebug[Hardware]and selectBuild. The Console window shows the build progression including thesds++system compiler invocation.
2. After the application successfully builds the target executable file (app_arraycopy.elf), the Assistant window populates with aData Motion NetworkReport, theCompilation Log, and anSD Card Imagemenu. Through theSD Card Imagemenu, the contents of the generated (sd_card) files directory is available to view using the Project Explorer, a file browser, or a command shell window.
3. When the build completes, you can write the contents of the generatedsd_carddirectory to the root of a FAT32-formatted SD card and boot and run theapp_arraycopy.elfapplication on a ZCU102 board. Thesd_carddirectory includes aREADME.txtfor boot setup instructions, a bootableBOOT.BINfile, and theimage.ubfile used to boot Linux.

TheSDxIDE builds the application with thesds++system compiler using the C-callable library and the application code. The main application is compiled to produce an object file and then it is linked with the C-callable library (arraycopy).

The following examples show the issued commands.

Compilation ofmain.cpp:

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-sys-config a53_linux -sds-proc a53_linux -sds-pf zcu102

Linkingmain.owitharraycopylibrary to produce executable applicationapp_arraycopy.elf:

sds++ -L --remote_ip_cache ../ip_cache \ -o app_arraycopy.elf ./src/main.o -larraycopy -dmclkid 1 \ -sds-sys-config a53_linux -sds-proc a53_linux -sds-pf zcu102