Importing Window-Based Kernels

As explained in Data Accessing Mechanisms, the size of the input and output data blocks for window-based access depends on the specified window size. Vitis Model Composer supports the following windows-based input and output data types as interfaces to the AI Engine kernel block.

input_window_<Type>
output_window_<Type>

<Type>	Complexity	Signedness
int8	Real	Signed
int16	Real	Signed
int32	Real	Signed
int64	Real	Signed
uint8	Real	Unsigned
uint16	Real	Unsigned
uint32	Real	Unsigned
uint64	Real	Unsigned
cint16	Complex	Signed
cint32	Complex	Signed
float	Real	N/A
cfloat	Complex	N/A

As an example, to import a simple kernel with a window-based interface, the following simple.h header file defines the add_kernel function with two input windows and one output window of type int16.

Simple.h

#ifndef __ADD_KERNEL_H__
#define __ADD_KERNEL_H__
 
#include <adf.h>
#define NUM_SAMPLES 4
void add_kernel(input_window_int16 * in1,input_window_int16 * in2, output_window_int16 * outw);
 
#endif

The kernel (simple.cc) is defined as follows. It processes a sum operation on in1 and in2 and produces output on outw.

#include "simple.h"
void add_kernel(input_window_int16 * in1,input_window_int16 * in2, output_window_int16 * outw)
{
    int16 temp1,temp2,temp_out;
    for (unsigned i=0; i<NUM_SAMPLES; i++) {
        window_readincr(in1,temp1);
        window_readincr(in2,temp2);
        temp_out = temp1 + temp2;
        window_writeincr(outw,temp_out);
    }
}

Tip: Although not required, the following recommendations are useful for reusability and faster compilation.

Define each kernel in its own source file.
Organize kernels by creating directories for header files and source files separately.
Kernel source files should include all relevant header files to allow for independent compilation.

To import the add_kernel function as a block in a Model Composer design, double-click the AIE Kernel block and update parameters as follows:

Kernel header file: kernels/include/simple.h
Kernel function: add_kernel
Kernel Init function: Leave empty
Kernel source file: kernels/source/simple.cc
Kernel search path: Leave empty
Preprocessor options: Leave empty

When you click the Import button in the Block Parameters dialog box, the tool parses the function signature in the header file and updates the AI Engine kernel block GUI interface as shown in the following figure.

Figure 1. AIE Kernel Block (Updated)

After the AIE Kernel block is added to the Simulink editor, input and output ports are not present. But, after adding the kernel parameters in the Block Parameters dialog box, the block is updated with two input ports and one output port with block name matching the imported kernel function.

After a successful import, the Function tab displays automatically, providing user-editable configuration parameters. You can quickly review the function definition of the imported kernel function and the port names with directions.

Figure 2. Function Tab

Appropriate values should be entered in the Function tab for Window size and Window margin (see the previous figure).

Setting the Window Margin Value

As explained in Data Accessing Mechanisms, window margin is the overlapping of input data samples. Model Composer accepts Window margin value in terms of the number of samples. The values given in the Window margin fields should be multiple of 32 bytes.

For example, if your input data type is int16 which is 2 bytes. The minimum Window margin value that is accepted is 16 samples (16*2). The other values that are accepted can be 32, 48, 64 and so on.

Another example. If your input is of type cint32 which is 8 bytes (real 4 bytes and 4 imaginary bytes). In this case the minimum window margin value that is accepted is 4. Because, 4 * 8 bytes gives 32 bytes. The other values that are accepted can be 8, 12, 16, and so on.

The following table provides details on the parameters and description for each parameter.

Table 1. Window Port Parameters
Parameter Name	Criticality	Description
Window size	Mandatory	Window size is required for each port (argument) of the kernel function. The value represents the number of samples (elements). The window size must be a positive integer value. Window size should be a multiple of 16 bytes.
Window margin	Mandatory	Window margin is required for each input port (argument) of the kernel function. The value represents the number of samples (elements). The window margin must be a non-negative integer. The window margin should be a multiple of 32 bytes.
Synchronicity	Mandatory	The Synchronicity value options available are `sync` and `async`. Port synchronicity is set to `sync` by default. You can optionally change it `async`.

After the successful import of kernel functions, the Import button label in the General tab changes to Update enabling further updates of block parameters. You can change the source code of the kernel function even after importing the block without requiring a re-import. However, if you change the function signature, or the parameters to the function, then you will need to click Update in the General tab to apply changes.

Figure 3. General Tab

Importing Window-Based Kernels - 2022.1 English

Vitis Model Composer User Guide (UG1483)

Simple.h

Setting the Window Margin Value