Defining Customization Parameters - 2025.2 English - UG1483

Vitis Model Composer User Guide (UG1483)
Document ID
UG1483
Release Date
2025-11-20
Version
2025.2 English

You can use template parameters to define port array sizing and data type. The block input signals define the parameters. You can also define additional customization parameters, which are not defined by input signals. You must define these using the Block Parameter dialog box before simulation runtime.

There are two methods to define customization parameters for a library function block:

  • Using C/C++ function templates.
  • Assigning the Model Composer (XMC) PARAMETER pragma to a function argument, defining it as not connecting to an input or output of the block, but rather as a customization parameter.

The following section discusses the advantages and disadvantages of both methods.

Function Templates

The first method, defines a function template that uses template parameters for customization. A template parameter defines a customization parameter in Model Composer if its value is not determined by an input signal, or a function output. You can use customization parameters to define the values, data types, or data dimensions of output ports. You can also use them as parameters in the function body.
Important: The template function signature and function definition must be defined in the C/C++ header file.

The standard function template syntax defines the template parameter for the function argument. However, the template parameter is not assigned to an input argument in the function signature. When the block is instantiated into a model, Model Composer identifies template parameters whose values are not determined by input signals. It lets you the values for those customization parameters. You can define values for customization parameters in the model at any time prior to simulation.

For function templates, the customization parameters can only be either of the following:

  • integer values to define the size or dimensions of a data type
  • scalar variables with definable data types.

Model Composer defines a default value of 0 for integer parameters, and 'int32' for data type, or typename parameters.

In the function template example below, the template parameters ‘M’ and 'B' define customization parameters because the parameter values are not inherited from the input signal to the block. In this case, you need to customze the parameters when the block is added to the model, or at any time before simulation.
template <int M, int B>
double func1(double x) {
   return x * M + B;
}

Customization parameters display in the Block Parameters dialog box for the imported block. The following figure shows this for the func1 function. Double-click a block in the model to open the Block Parameters dialog box, then enter the value for any editable parameters, such as 'M' and 'B' below.

Figure 1. Entering Parameter Values

Optionally, you can enter a MATLAB workspace variable name in the text field for the customization parameter. Model Composer then uses that variable to determine the customization parameter’s value. For example, the variable param1 is defined in the MATLAB workspace, and used to define the value for 'M'.

Figure 2. Defining Parameters using Workspace Variables

PARAMETER Pragma

The second method defines function arguments as customization parameters through the use of the Model Composer PARAMETER pragma.

To declare that a function argument is a customization parameter, you must add the PARAMETER pragma with the parameter name, or list of names, before the function signature in the header file. You can specify multiple parameters with one pragma, or have separate pragmas for each, as shown below.
#pragma XMC PARAMETER <name1>, <name2>
#pragma XMC PARAMETER <name3>
function declaration(<name1>, <name2>, <name3>)

When a pragma declares a function argument a customization parameter, the xmcImportFunction command does not create an input or output port on the block for that argument. It is defined for use inside the function body only. When the block is added to a model, a customization field is added to the Block Parameter dialog box, and you can define values for the customization parameters.

Using the PARAMETER pragma on a function argument that is already driven by the input signal flags an error or a warning. In this case, the signal input propagation through the function has higher precedence than the customization parameter.

While the function templates method only supports scalar and integer type customization parameters, the PARAMETER pragma supports integer, floating point or fixed point data type for the parameters. The customization parameters also can be scalar, vector or a two-dimensional matrix. In addition, while the function template defines default values of 0 for integer types, and int32 for the data type, the PARAMETER pragma lets you define default value for the parameters. Model Composers defines default values of 0 for all parameters that do not have user-defined defaults.

The example below uses the Model Composer PARAMETER pragma to define the customization parameters 'M' and 'B'.

#pragma XMC PARAMETER M, B
double func2(double x, double M = 1.2, double B = 3) {
return x * M + B;
}

The 'M' and 'B' customization parameters also have default values assigned: M=1.2, B=3. The default values for the customization parameters are assigned to the arguments in the function signature. These values are in the Block Parameters dialog box when opened for edit, as shown below.

Figure 3. Customization Parameters with Defaults
Important: If you define default values for the customization parameters of any argument, the C/C++ language requires that all arguments following that one must also have default values assigned. This is because you can call the function without arguments having default values. Therefore, add all customization parameters with default values at the end of the function argument list.

Vector and Matrix Customization Parameters

You can use the PARAMETER pragma method to specify customization parameters with vector and matrix dimensions, or values. In the following example the coef vector is defined by the pragma as a customization parameter:
#pragma XMC PARAMETER coef
#pragma XMC INPORT din
#pragma XMC OUTPORT dout 
#pragma XMC SUPPORTS_STREAMING
void FIR(ap_fixed<17, 3> din[100], ap_fixed<17, 3> dout[100], 
ap_fixed<16, 2> coef[52]);
Enter the constant array values of the customization parameter in MATLAB expression format.
Note: commas are optional:
  • Vector parameter: [val1, val2, val3, ...]
  • Matrix parameter (row-major order): [val11, val12, val13, ...; val21, val22, val23, ...; ...]

Interface Output Types and Sizes

You can use customization parameters to set data types and dimension sizes for output ports when inputs to the function do not define them. In the function below, the template variables define the word length and fractional length of the ap_fixed data type and the array size.

template <typename T1, int N1, int W2, int I2, int N2>
void func(const T1 in[N1], ap_fixed<W2, I2> out[N2]) {
...
}

The template variables 'W2, 'I2'' and 'N2' define customization parameters because the values must be set by the user rather than the input arguments. However, Model Composer recognizes that the template variables 'T1' and 'N1' are specified on the input port. This means the data type (typename) and the size of the input vector are not customization parameters, but are defined by the input signal on the block.

To set the data type for output ports, or arguments used in the body of the function, the typename specified must be one of the Model Composer supported data types, including the signed or unsigned fixed data types.

Model Composer Supported Data Types

Supported Typenames
  • 'int8'
  • 'uint8'
  • 'int16'
  • 'uint16'
  • 'int32'
  • 'uint32'
  • 'double'
  • 'single'
  • 'x_half''
  • 'boolean'
  • 'x_sfix<n1>_En<n2>'
  • 'x_ufix<n1>_En<n2>'

In the example function below, while the typename for 'T1' is determined by the input signal, you can set the typename for 'T2' in the Block Parameters dialog box on the mask. You can do this after adding the block to a model, or before simulation runtime:

template <typename T1, int N1, typename T2, int N2>
void func(const T1 in[N1], T2 out[N2]) {
...
}