Using the xmcImportFunction Command - 2025.2 English - UG1483

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

• libName: This string specifies the name of the Model Composer HLS library that the new block joins. This can be a new, or 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 needs to be the full path to the header file if it does not reside 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: You must define the function signature in the header file. Also, specify any Model Composer (XMC) pragmas 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, are compiled into the shared library for simulation. These are also 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': Unlocks a locked library. 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 is searched for the specified files.
  Tip: Model Composer shows a warning if you try to import a block with a function name already used in the specified library.

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

Figure 1. simple_add Block

Simulation compiles the C/C++ code for the Library blocks and creates and loads a library file. The library file is 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. However the cached library file is updated if you change the C/C++ source code.

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

After creating the block symbol, you can double-click the symbol to view the parameters of the imported block. You can quickly review the parameters as shown in the following figure to ensure the function ports are properly defined.

Figure 2. simple_add Block Parameters