AI Engine Series 1 - Starting out with the AI Engine tools

[florentw]

Introduction to the AI Engine Series

Last July, in the article titled Versal ACAP AI Engines for Dummies I introduced the AI Engine (AIE) array which is present in some Versal™ ACAP devices. In this new series of articles, the AI Engine Series, we will provide some examples of how to use the AI Engine tools integrated into the Vitis™ 2020.2 unified software platform.

Requirements

This tutorial requires that you have the following:

• A basic understanding of Xilinx tools
• A basic knowledge of C/C++ programming languages
• The Vitis 2020.2 unified software platform installed on a supported Linux OS
• A valid license for the AI Engine tools (licenses are included in the VCK190 kit and are not sold separately)
• The VCK190 base platform downloaded from Xilinx.com (link) or from GitHub (link)

Introduction

I like to view a Versal System as having 3 main domains. The AI Engine (AIE) domain, the Processing System (PS) domain and the Programmable Logic (PL) domain. To run an AIE application on Versal, it is most likely that you will need to use the 3 domains, all working together.

This article is focused on the programming of AIE domain using the Vitis™ unified software platform.

Tutorial : Introduction to the Xilinx tools

1. Open the Vitis 2020.2 unified software platform IDE and select a workspace repository
   
   
2. On the welcome page click on Create Application Project
   
   
   
   If you do not see the welcome page click File > New > Application Project
   
   
3. Click Next on the welcome page if it appears:
   
   
   
   
   
4. In the Platform selection page, select the xilinx_vck190_base_202020_1 platform and click Next.
   
   Note: if you do not see a platform named xilinx_vck190_base_202020_1 listed, make sure you have downloaded it from GitHub or Xilinx.com and add the repository using the Add button:
   
   

We can see that the VCK190 base platform has 2 domains defined:

• the aiengine domain targeting the AI Engine array
• the xrt domain targeting the ARM cortex a72 (PS) running a Linux OS
  
  

5. Click Next.
   
   
6. Create a new application called simple_application and select ai_engine as the target processor. Click Next.
   
   
7. Click Next on the Domain page.
   
   
8. On the Templates page select the Simple template and click Finish.
   
   Important: you will see a note in the description window that states "This templates works only for AIE simulation and SW(x86)". The reason for this is that the template does not include any I/O to feed the AIE application or any PS application which will be required for a full system running in hardware.
   
   From the Explorer window we can see that multiple sets of files were imported:
   simple_application is our application running on the AI Engine
   simple_application/src is the directory containing the sources that will be compiled to run on the AI Engine array
   simple_application/src/kernels is the directory which contains the source code for the kernels
   simple_application/data is the directory containing the simulation files
   
9. Open simple_application.prj under simple_application from the explorer window. In the window showing the details we can see that there is one file, project.cpp from the src folder, which is defined as a Top-Level file.
   
   
   Note: It is a requirement to define the top level file for an AI Engine application. This file contains the instantiation of the top level graph (refer to Versal ACAP AI Engines for Dummies for the definition of a graph)
   
   
10. Open the file project.cpp from the Explorer window. For a complete description of the syntax, refer to UG1076 - Versal ACAP AI Engine Programming Environment. 
    
    

The include headers (Line 3 > Line 5) add the adf dataflow library (adf.h), the top-level graph declaration file (project.h) and the kernel functions prototypes (kernels.h). 

On Line 9, a graph from the class simpleGraph is instantiated along with an instance called mygraph.

On Line 10, the simulation platform is declared with 1 input port and 1 output port using a predefined class constructor - adf::simulation::platform<1,1>. It also specifies the input data file (data/input.txt) which contains values that are input to the dataflow graph, and the output file (data/output.txt) where the output will be stored after execution (in simulation only).

On Lines 11 and 12, the graph input and output are connected to the simulation platform.

Finally, on line 14 to 19, there is the main function in which the graph is initialized, run for 4 iterations, and then terminated.

Based on what we have seen we can draw the graph as a black box with its input and its output connected to the platform:

In the next entry in this series, we will have a closer look in the graph and the kernels.