Importing AI Engine Graphs - 2022.1 English

Vitis Model Composer User Guide (UG1483)

Document ID
UG1483
Release Date
2022-05-26
Version
2022.1 English

As discussed in AI Engine Graphs, a graph is a connection of different compute kernel functions. Unlike when importing kernels, where a kernel function is imported as a block into Model Composer, in this case, graph code is imported as a block. To import the graph as block into Vitis Model Composer, you need to select the AIE Graph block from the AI Engine library (shown in the following figure).

Figure 1. AIE Graph

Vitis Model Composer allows connection between the AIE Graph block and the AIE Kernel block so that the whole design can be simulated in the Simulink environment.

Important: It is assumed that your kernel code is already developed and that the associated kernels are properly organized.

The AIE Graph block supports importing the AI Engine graph into Model Composer in two ways:

  • Using the header file (*.h)
  • Using the source file (*.cpp)

Using the Header File

To import the graph using the header file (.h), double-click the AIE Graph block and select the Header file (*.h) option in the General tab. Specify the graph header file, class, search path, and preprocessor options as shown in the following figure.

Figure 2. AIE Graph Block Parameters Dialog Box

The following table provides further details including names and descriptions of each parameter.

Table 1. AIE Graph Block Parameters
Parameter Name Parameter Type Criticality Description
Graph application file (*.h) String Mandatory Specify the file (.h), where the application graph class is defined and the Adaptive Data Flow (ADF) header (adf.h), kernel function prototypes are included.
Graph class String Mandatory Specify the name of the graph class.
Graph Search paths Vector of strings Mandatory Specify search paths where header files, kernels, and other include files can be found and included for simulation. The search path $XILINX_VITIS/adf/include (where adf.h is defined) is included by default and does not need to be specified.
Preprocessor options   Optional Optional preprocessor arguments for downstream compilation with specific preprocessor options. The following preprocessor option formats are accepted and multiple can be selected: ‘-D<name>’ and ‘-D<name>=<definition>’. That is, the optional argument must begin with the '-D' string and if the optional <definition> value is not provided, it is assumed to be 1.

graph.h

#ifndef __XMC_PROJ_H__
#define __XMC_PROJ_H__
 
#include <adf.h>
#include "simple.h"
 
class Proj_base : public adf::graph {
public:
   adf::kernel AIE_Kernel;
 
public:
   adf::input_port In1, In2;
   adf::output_port Out1, Out2;
 
   Proj_base() {
      // create kernel AIE_Kernel
      AIE_Kernel = adf::kernel::create(simple_comp_1);
      adf::source(AIE_Kernel) = "simple.cc";
 
      // create kernel constraints AIE_Kernel
      adf::runtime<ratio>( AIE_Kernel ) = 0.9;
 
      // create nets to specify connections
      adf::connect< adf::stream > net0 (In1, AIE_Kernel.in[0]);
      adf::connect< adf::stream > net1 (In2, AIE_Kernel.in[1]);
      adf::connect< adf::stream > net2 (AIE_Kernel.out[0], Out1);
      adf::connect< adf::stream > net3 (AIE_Kernel.out[1], Out2);
   }
};
 
class Proj : public adf::graph {
public:
   Proj_base mygraph;
 
public:
   adf::input_plio In1, In2;
   adf::output_plio Out1, Out2;
 
   Proj() {
      In1 = adf::input_plio::create("In1",
            adf::plio_32_bits,
            "./data/input/In1.txt");
 
      In2 = adf::input_plio::create("In2",
            adf::plio_32_bits,
            "./data/input/In2.txt");
 
      Out1 = adf::output_plio::create("Out1",
            adf::plio_32_bits,
            "Out1.txt");
 
      Out2 = adf::output_plio::create("Out2",
            adf::plio_32_bits,
            "Out2.txt");
 
      adf::connect< > (In1.out[0], mygraph.In1);
      adf::connect< > (In2.out[0], mygraph.In2);
      adf::connect< > (mygraph.Out1, Out1.in[0]);
      adf::connect< > (mygraph.Out2, Out2.in[0]);
   }
};
 
#endif // __XMC_PROJ_H__
Note: It is not allowed to import the graph class that has PLIO attributes specified. Model Composer will throw an appropriate error if you try to do so. In this case, use the Proj_base class to import the graph.

When the GUI parameters are updated, click the Import button. The tool updates the Block Parameters dialog box as shown. In the Graph Class tab you can see the RTP column with check boxes. You can check this ON, only if the port is a Run Time Parameter. If not, you can directly click Build at the bottom.

Figure 3. Block Parameters Dialog Box

The Block Parameters dialog box updates as shown in the following figure. This contains the port direction and type.

Figure 4. Block Parameters Dialog Box

Parameters such as the Graph Port Name, Data Type etc. are automatically updated from the graph code. The only user-editable function configuration parameter is the Signal size.

Table 2. User Editable Parameter
User-Editable Parameter Criticality Description
Signal size Mandatory This parameter represents the size of the output signal and should be set to a value equal to or greater than the number of samples that are produced at every invocation of the kernel.

The AIE Graph block GUI interface with input and output ports is as shown in the following figure.

Figure 5. AIE Graph Block

In the General tab, the Import button changes to Update, enabling further update of block parameters.

Figure 6. Update Button

Using the Source File (*.cpp)

To import the graph using the source file (.cpp), double-click the AIE Graph block and select the Source file (*.cpp) option in the General tab. Specify the graph application file (*.cpp), search paths, and preprocessor options as shown in the following figure.

Figure 7. AIE Graph Block Parameters Dialog Box

The following table provides further details including names and descriptions of each parameter.

Table 3. AI E Graph Block Parameters
Parameter Name Parameter Type Criticality Description
Graph application file String Mandatory Specify the file (.cpp), where the ADF dataflow graph is instantiated and connected to simulation platform. This file should contain the main() function, from where the dataflow graph initializes and runs.
Graph search paths Vector of strings Mandatory Specify search paths where header files, kernels, and other include files can be found and included for simulation. The search path $XILINX_VITIS/adf/include (where adf.h isdefined) is be included by default and does not need to be specified.
Preprocessor options   Optional Optional preprocessor arguments for downstream compilation with specific preprocessor options. The following preprocessor option formats are accepted and multiple can be selected: ‘-D<name>’ and ‘-D<name>=<definition>’. That is, the optional argument must begin with the '-D' string and if the optional <definition> value is not provided, it is assumed to be 1.

The following example shows the sample graph .cpp file. The graph is connected as follows. This file should be pointed to the Graph application file field in the Block Parameters dialog box.

graph.cpp

#include "Proj.h"
 
// instantiate cardano dataflow graph
Proj mygraph;
 
// initialize and run the dataflow graph
#if defined(__AIESIM__) || defined(__X86SIM__)
int main(void) {
   mygraph.init();
   mygraph.run();
   mygraph.end();
   return 0;
}
#endif

When the GUI parameters are updated, click Import. The tool generates the graph database and after successful import the AI Engine graph block gets updated with input and output ports as shown in the following figure.

Figure 8. AIE Graph Block

Notice that the AIE Graph block interface generated when importing the header file and the source file remains the same.

The Function Tab in the AIE Graph Block Parameters dialog box appears similar to the one shown in the Import graph using the header file. You can update the Signal size parameter and click OK to exit the Block Parameters dialog box.

Important:
  • To connect an AI Engine graph inout port to an AI Engine graph input RTP port, the synchronocities of both ports must be compatible, otherwise, an appropriate error is reported by Model Composer.
  • If the RTP port's behavior is different from its default behavior, the connection should appropriately specify it as an async or sync port in graph code.