Using the xmcImportFunction Command - 2022.2 English

xmcImportFunction('libName',{'funcNames'},'hdrFile',{'srcFiles'},
{'srchPaths'},'options')

• libName: A string that specifies the name of the Model Composer HLS library that the new block is added to. The library can be new, and will be created, or can be an existing library.
• funcNames: Specifies a list (cell array) of one or more function names defined in the source or header files to import as a Model Composer block. An empty set, {}, imports all functions defined in the specified header file (hdrFile). For functions inside namespaces, full namespace prefix needs to be given. For example, to import the function 'sinf' in hls_math, the full function name 'hls::sinf' needs to be specified.
• hdrFile: A string that specifies a header file (.h) which contains the function declarations, or definitions. This should be the full path to the header file if it is not residing inside the current working directory. For example, to import a function from hls_math.h, you need to specify the full path '$XILINX_VIVADO/include/hls_math.h'.
  Important: The function signature must be defined in the header file, and any Model Composer (XMC) pragmas must be specified as part of the function signature in the header file.
• srcFiles: Specifies a list of one or more source files to search for the function definitions. When used in a model, the header and source files, together with the main header file of the model, headerFile, will be compiled into the shared library for simulation, and copied into the Target Directory specified for output generation in the Model Composer Hub block, as described in Vitis Model Composer Hub.
• srchPaths: Specifies a list of one or more search paths for header and source files. An empty set, {}, indicates no search path, in which case the code is looked for in the MATLAB current folder. Use '$XILINX_VIVADO/include' to include the HLS header files.

In addition, the xmcImportFunction command has the following options, which can follow the required arguments in any order:

• 'unlock': Unlock an existing library if it is locked. The xmcImportFunction command can add blocks to an existing library, but it must be unlocked to do so.
• 'override': Overwrite an existing block with the same name in the specified library.

As an example, the following simple.h header file defines the simple_add function, with two double-precision floating point inputs and a pointer output. The function simply adds the two inputs and returns the sum as the output.

void simple_add(const double in1, const double in2, double *out) {
   *out = in1 + in2;
}

xmcImportFunction('SimpleLib',{'simple_add'},'simple.h',{},{})

• SimpleLib is the name of the Model Composer HLS library to add the block to.
• simple_add is the function name to import.
• simple.h is the header file to look in.
• No C source files or search paths are specified. In this case, the function definition must be found in the specified header file, and only the MATLAB current folder will be searched for the specified files.
  Tip: Model composer will give you a warning if you attempt to import a block with the same function name as a block that is already in the specified library.

When xmcImportFunction completes, the SimpleLib library model will open with the simple_add block created as shown below.

Figure 1. simple_add Block

During simulation, the C/C++ code for the Library blocks will get compiled and a library file will get created and loaded. The library file will be cached to speed up initializing simulations on subsequent runs. You can change the source code underlying the library block without the need to re-import the block, or re-create the library, although the cached library file will be updated if you change the C/C++ source code.

However, if you change the function signature, or the parameters to the function, then you will need to rerun the xmcImportFunction command to recreate the block. In this case, you will also need to use the override option to overwrite the existing block definition in your library.

After the block symbol has been created, you can double-click on the symbol to see the parameters of the imported block. You can quickly review the parameters as shown in the following figure to ensure the function ports have been properly defined.

Figure 2. simple_add Block Parameters