AI Engine Programming

1. Define your application graph class in a separate header file (for example project.h). First, add the Adaptive Data Flow (ADF) header (adf.h) and include the kernel function prototypes. The ADF library includes all the required constructs for defining and executing the graphs on AI Engines.

   #include <adf.h>
   #include "kernels.h"

2. Define your graph class by using the objects which are defined in the adf name space. All user graphs are derived from the class graph.

   include <adf.h>
   #include "kernels.h"
   
   using namespace adf;
   
   class simpleGraph : public graph {
   private:
     kernel first;
     kernel second;
   };

   This is the beginning of a graph class definition that declares two kernels (first and second).

3. Add some top-level ports to the graph.

   #include <adf.h>
   #include "kernels.h"
   
   using namespace adf;
   
   class simpleGraph : public graph {
   private:
     kernel first;
     kernel second;
   public:
     input_port in;
     output_port out;
   
   };

4. Use the kernel::create function to instantiate the first and second C++ kernel objects using the functionality of the C function simple.

   #include <adf.h>
   #include "kernels.h"
   
   using namespace adf;
   
   class simpleGraph : public graph {
   private:
     kernel first;
     kernel second;
   public:
     input_port in;
     output_port out;
     simpleGraph() {
         first = kernel::create(simple);
         second = kernel::create(simple);
     }
   };

5. Add the connectivity information, which is equivalent to the nets in a data flow graph. In this description, ports are referenced by indices. The first input window or stream argument in the simple function is assigned index 0 in an array of input ports (in). Subsequent input arguments take ascending consecutive indices. The first output window or stream argument in the simple function is assigned index 0 in an array of output ports (out). Subsequent output arguments take ascending consecutive indices.

   #include <adf.h>
   #include "kernels.h"
   
   using namespace adf;
   
   class simpleGraph : public graph {
   private:
     kernel first;
     kernel second;
   public:
     input_port in;
     output_port out;
   
     simpleGraph() {
       first = kernel::create(simple);
       second = kernel::create(simple);
       connect< window<128> > net0 (in, first.in[0]);
       connect< window<128> > net1 (first.out[0], second.in[0]);
       connect< window<128> > net2 (second.out[0], out);
     }
   };

   As shown, the input port from the top level is connected into the input port of the first kernel, the output port of the first kernel is connected to the input port of the second kernel, and the output port of the second kernel is connected to the output exposed to the top level. The first kernel executes when 128 bytes of data (32 complex samples) are collected in a buffer from an external source. This is specified as a window parameter at the connection net0. Likewise, the second kernel executes when its input window has valid data being produced as the output of the first kernel expressed via connection net1. Finally, the output of the second kernel is connected to the top level output port as connection net2, specifying that upon termination the second kernel will produce 128 bytes of data.

6. Set the source file and tile usage for each of the kernels. The source file kernel.cc contains kernel first and kernel second source code. Then the ratio of the function run time compared to the cycle budget, known as the run-time ratio, and must be between 0 and 1. The cycle budget is the number of instruction cycles a function can take to either consume data from its input (when dealing with a rate limited input data stream), or to produce a block of data on its output (when dealing with a rate limited output data stream). This cycle budget can be affected by changing the block sizes.

   #include <adf.h>
   #include "kernels.h"
   
   using namespace adf;
   
   class simpleGraph : public graph {
   private:
     kernel first;
     kernel second;
   public:
     input_port in;
     output_port out;
     simpleGraph(){
       
       first = kernel::create(simple);
       second = kernel::create(simple);
       connect< window<128> > net0 (in, first.in[0]);
       connect< window<128> > net1 (first.out[0], second.in[0]);
       connect< window<128> > net2 (second.out[0], out);
   
       source(first) = "kernels.cc";
       source(second) = "kernels.cc";
   
       runtime<ratio>(first) = 0.1;
       runtime<ratio>(second) = 0.1;
   
     }
   };

   Note: See Run-Time Ratio for more information.
7. Define a top-level application file (for example project.cpp) that contains an instance of your graph class and connect the graph to a simulation platform to provide file input and output. In this example, these files are called input.txt and output.txt.

   #include "project.h"
   
   simpleGraph mygraph;
   simulation::platform<1,1> platform(“input.txt”,”output.txt”);
   connect<> net0(platform.src[0], mygraph.in);
   connect<> net1(mygraph.out, platform.sink[0]);
   
   int main(void) {
     adf::return_code ret;
     mygraph.init();
     ret=mygraph.run(<number_of_iterations>);
     if(ret!=adf::ok){
       printf("Run failed\n");
       return ret;
     }
     ret=mygraph.end();
     if(ret!=adf::ok){
       printf("End failed\n");
       return ret;
     }
     return 0;
   }

ADF APIs have return enumerate type return_code to show the API running status.

The main program is the driver for the graph. It is used to load, execute, and terminate the graph. See Run-Time Graph Control API for more details.

1. To compile your graph, execute the following command (see Compiling an AI Engine Graph Application for more details).

   aiecompiler  project.cpp

   The program is called project.cpp. The AI Engine compiler reads the input graph specified, compiles it to the AI Engine array, produces various reports, and generates output files in the Work directory.

2. After parsing the C++ input into a graphical intermediate form expressed in JavaScript object notation (JSON), the AI Engine compiler does the resource mapping and scheduling analysis and maps kernel nodes in the graph to the processing cores in the AI Engine array and data windows to memory banks. The JSON representation is augmented with mapping information. Each AI Engine also requires a schedule of all the kernels mapped to it.

   The input graph is first partitioned into groups of kernels to be mapped to the same core.

   The output of the mapper can also be viewed as a tabular report in the file project_mapping_analysis_report.txt. This reports the mapping of nodes to processing cores and data windows to memory banks. Inter-processor communication is appropriately double-banked as ping-pong buffers.

3. The AI Engine compiler allocates the necessary locks, memory buffers, and DMA channels and descriptors, and generates routing information for mapping the graph onto the AI Engine array. It synthesizes a main program for each core that schedules all the kernels on the cores, and implements the necessary locking mechanism and data copy among buffers. The C program for each core is compiled using the Synopsys Single Core Compiler to produce loadable ELF files. The AI Engine compiler also generates control APIs to control the graph initialization, execution and termination from the main application and a simulator configuration script scsim_config.json. These are all stored within the Work directory under various sub-folders (see Compiling an AI Engine Graph Application for more details).
4. After the compilation of the AI Engine graph, the AI Engine compiler writes a summary of compilation results called <graph-file-name>.aiecompile_summary to view in the Vitis analyzer. The summary contains a collection of reports, and diagrams reflecting the state of the AI Engine application implemented in the compiled build. The summary is written to the working directory of the AI Engine compiler as specified by the --workdir option, which defaults to ./Work.

   To open the AI Engine compiler summary, use the following command:

   vitis_analyzer ./Work/graph.aiecompile_summary

5. To run the graph, execute the following command (see Simulating an AI Engine Graph Application for more details).

   aiesimulator –-pkg-dir=./Work

   This starts the SystemC-based simulator with the control program being the main application. The graph APIs which are used in the control program configure the AI Engine array including setting up static routing, programming the DMAs, loading the ELF files onto the individual cores, and then initiates AI Engine array execution.

   At the end of the simulation, the output data is produced in the directory aiesimulator_output and it should match the reference data.

   The graph can be loaded at device boot time in hardware or through the host application. Details on deploying the graph in hardware and the flow associated with it is described in detail in Integrating the Application Using the Vitis Tools Flow.