Preparing the XSI Functions for Dynamic Linking - 2021.2 English

Vivado Design Suite User Guide: Logic Simulation (UG900)

Document ID
UG900
Release Date
2021-10-22
Version
2021.2 English

Xilinx recommends the usage of dynamic linking for indirectly calling the XSI functions. While this technique involves more steps than simply calling XSI functions directly, dynamic linking allows you to keep the compilation of your HDL design independent of the compilation of your C/C++ program. You can compile and load your HDL design at any time, even while your C/C++ program continues to run.

To call a function through dynamic linking requires your program to perform the following steps:

  1. Open the shared library containing the function.
  2. Look up the function by name to get a pointer to the function.
  3. Call the function using the function pointer.
  4. Close the shared library (optional).

Steps 1, 2, and 4 require the use of OS-specific library calls, as shown in the following table. See your operating system documentation for details about these functions.

Table 1. Operating System Specific Library Calls
Function Linux Windows
Open shared library
void *dlopen(const char 
*filename, int flag);
HMODULE WINAPI 
LoadLibrary(_In_ LPCTSTR 
lpFileName
);
Look up function by name
void *dlsym(void 
*handle, const char 
*symbol);
FARPROC WINAPI 
GetProcAddress(_In_ 
HMODULE hModule,_In_ 
LPCSTR lpProcName
);
Close shared library
int dlclose(void 
*handle);
BOOL WINAPI 
FreeLibrary(_In_ HMODULE 
hModule
);

XSI requires you to call functions from two shared libraries: the kernel shared library and your design shared library. The kernel shared library ships with the Vivado simulator and is called librdi_simulator_kernel.so (Linux) or librdi_simulator_kernel.dll (Windows). It resides in the following directory:

<Vivado Installation Root>/lib/<platform>

where <platform> is lnx64.o or win64.o. Make sure to include this directory in your library path while running your program. On Linux, include the directory in the environment variable LD_LIBRARY_PATH, and on Windows, in the environment variable PATH.

Your design shared library, which the Vivado simulator creates in the course of compiling your HDL design, as described in Preparing the Design Shared Library, is called xsimk.so (Linux) or xsimk.dll (Windows) and typically resides at the following location:

<HDL design directory>/xsim.dir/<snapshot name>

where <HDL design directory> is the directory from which your design shared library was created, and <snapshot name> is the name of the snapshot that you specify during the creation of the library.

Your C/C++ program will call the XSI function xsi_open() residing in your design shared library and all other XSI functions from the kernel shared library.

The XSI code examples that ship with the Vivado simulator consolidate the XSI functions into a C++ class called Xsi::Loader. The class accepts the names of the two shared libraries, internally executes the necessary dynamic linking steps, and exposes all the XSI functions as member functions of the class. Wrapping the XSI functions in this manner eliminates the necessity of calling the dynamic linking OS functions directly. You can find the source code for the class that can be copied into your own program at the following location under your Vivado installation:

<Vivado Installation Root>/examples/xsim/verilog/xsi/counter/xsi_loader.h
<Vivado Installation Root>/examples/xsim/verilog/xsi/counter/xsi_loader.cpp

To use Xsi::Loader, simply instantiate it by passing the names of the two shared libraries as shown in the following example:

#include "xsi_loader.h"
...
Xsi::Loader loader("xsim.dir/mySnapshot/xsimk.so", "librdi_simulator_kernel.so");