Importing Window-Based Kernels - 2022.2 English

Vitis Model Composer User Guide (UG1483)

Document ID
UG1483
Release Date
2023-01-13
Version
2022.2 English

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