Revision History - 2022.1 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)

Document ID
Release Date
2022.1 English

The following table shows the revision history for this document.

Section Revision Summary
05/25/2022 Version 2022.1
AI Engine Compiler Options Added note that two reserved words, aie and adf, are not valid namespace identifiers in graph programming
Viewing Compilation Results in the Vitis Analyzer Updated graphs for the 2022.1 release.
Programmable Logic (PL), Nets, and Tiles Updated example details and Vitis Analyzer GUI screen captures for the 2022.1 release.
Interface Channels Added new graph interface channel details.
Event Profile APIs for Graph Inputs and Outputs Added details for events on nets.
Viewing Guidance Using Vitis Analyzer Added this guidance.
Generating Traffic for Simulation and Emulation Clarified that you can write the external traffic generator in HDL, in addition to C++, and Python.
04/26/2022 Version 2022.1
Overview Updated Vitis core development kit details for the 2022.1 release.
Creating a Data Flow Graph (Including Kernels) Updated to the 2022.1 programming model.
Synchronous Window Access Added sections to explain window to window broadcasting, and multi-rate design support.
Stream-Based Access Added section to explain stream-based access using cascade stream.
Using Streams in Parallel Updated list of 32-bits and 64-bit macros.
Run-Time Parameter Support Summary Removed AI engine-to-AI engine run time parameter constructs, which are no longer supported.
Multicast Support Updated Multicast Support Scenarios table.
Design Flow Using RTL Programmable Logic Updated examples to reflect 2022.1 programming model changes.
Graph Programming Model Updated programming model details and examples throughout the chapter.
AI Engine Compiler Options Added new multi-rate options.

Updated --Xrouter=<string> example.

Mapper and Router Options Removed enableSplitAsBroadcast option (always on).

Added disablePathBalancing option.

x86 Functional Simulator Added ability to visualize X86 simulation output in Vitis Analyzer.
Compiling the Design Added X86 simulator options.
Data Snapshots Added ability to visualize snapshots in Vitis Analyzer.
Limitations Removed 'Simulation Output File Processing Considerations' and 'adf::headers Constraint and aie_api Include Files' sections because these x86 simulation limitations have been addressed.
Simulator Options Added new options, and hang detection details.
Enabling Third-Party Simulators Updated VCS details.

Added Riviera simulator information.

Profiling the AI Engine in Hardware

Profiling for Interface Tiles

Profiling the AI Engine, Memory Modules and Interface Tiles

Added the events used for DMA write/read_bandwidths.

Added the ability to profile interface events.

FIFO Depth Visualization in Vitis Analyzer Add ability to visualize DMA FIFO Depth in Vitis Analyzer from simulation VCD data.

XRT Flow

Added ability to specify event trace start time.

Added ability to periodically offload trace data at regular intervals.

Viewing Profiling Results Using Vitis Analyzer Added interface metrics example.

Added ability to consolidate multiple profile results in Vitis Analyzer.

Analyzing AI Engine Status in Hardware

Generating AI Engine Status

Analyzing AI Engine Status in Vitis Analyzer

Added ability to report out AI Engine status in hardware, and added ability to open and analyze the report in Vitis Analyzer.
Targeting the DFX Platform Added ability to use the DFX platform in addition to the base platform, and added information on using this platform in hardware.
Multi-Process and Multi-Thread Support for Controlling the AI Engine Graph Add clarification about xrtGraphClose and xrtDeviceClose behavior.
Platforms Updated Types of Platforms to include DFX platforms.
Performance Metrics Added Show Percentage button description.
Lock Stall Analysis

Stream Stall Analysis

Cascade Stall Analysis

Memory Stall Analysis

Added program counter (PC) option, which allows you to cross-probe to the source code from the Trace view in Vitis Analyzer.
Generating Traffic for Simulation and Emulation

Creating Traffic Generators in Python and C++

Added support for using traffic generators in x86 functional simulator, AI Engine simulator, software emulation, and hardware emulation. These traffic generators can be written in Python, C++, or HDL.
Host Programming for Bare-Metal

Building a Bare-Metal System

Host Programming Support Comparison Between Linux and Bare-Metal

Added details about Bare-Metal software stack.

Compared and contrasted the capabilities of running host application in Bare-Metal vs. Linux operating systems.

Integrating the Application Using the Vitis Tools Flow

Linking the System

Packaging the System

Updated to reflect the fact that v++ link now produces an XSA file.
AI Engine Hardware Profile and Debug Methodology New chapter about the AI engine hardware profile and debug methodology.


Updated document to reflect changes to programming models, which includes input_gmio/output_gmio, and input_plio/output_plio.
Other Constraints Added the repetition_count constraint for multi-rate designs.
12/17/2021 Version 2021.2
Window and Streaming Data API Added more supported unsigned integer data types.
Specifying Run-Time Data Parameters Clarified description.
Programming Model Features Changed heading of section.
AI Engine Compiler Options Added Table 10
Profiling the AI Engine New section.
Profiling Graph Throughput Added information.
Profiling the AI Engine in Hardware New section.
Event Tracing in Hardware New section.
Hardware Event Trace New section.
Troubleshooting Event Trace in Hardware New section.
10/22/2021 Version 2021.2
AI Engine Tile Architecture Updated Figure 1.
Prepare the Kernels Updated for AI Engine API.
Creating a Data Flow Graph (Including Kernels) Figure representing graph connectivity added.
Window and Streaming Data API Updated data types for AI Engine API and template support.
Packet Switching Graph Constructs Added an example for floating-point data.
Area Location Constraints New section.
Hierarchical Constraints Added information.
Programming Model Features New section.
AI Engine Compiler Options New options added.
Simulating an AI Engine Graph Application Added simulation flow related information.
Data Snapshots New section.
Deadlock Detection New section.
Trace Report New section.
Memory Access Violations and Valgrind New section.
Memory Model Updated information.
Simulation Output File Processing Considerations New section.
adf::headers Constraint and aie_api Include Files New section.
Software Emulation New section.
Simulator Options New option added.
Hardware Emulation New section.
Reusing AI Engine Simulator Options Added information about setting the AI Engine compiler workdir environment variable, as well as manual creation of the sim options file.
AI Engine Simulation-Based Profiling New section.
Supported Window Data Types Updated data types.
Supported Stream Data Types
AI Engine Stall Analysis in Vitis Analyzer New section.
Multi-Process and Multi-Thread Support for Controlling the AI Engine Graph New section.
AI Engine Error Events Updated errors, as well as debug tips.
Running Software Emulation New section.
Area Group Constraint Updated properties.
Creating the AI Engine Graph Project and Top-Level System Project Updated screenshots.
Building and Running the System Updated to add software emulation.
Debugging the AI Engine Application Debug information added.
Software Emulation Debug from the Vitis IDE New section.
Running Software Emulation from the Command Line New section.
Using the Debug Environment Updated screenshots.
Watchpoints New section.
Vitis IDE Layout for Software Emulation Debug New section.
Non-Templated Versions of Window and Stream APIs Appendix describing non-templated version of window and stream data types and APIs.
07/19/2021 Version 2021.1
FIFO Location Constraints Updated FIFO constraints examples.
Supported Window Data Types New topic.
Supported Stream Data Types New topic.
Building a Bare-metal AI Engine in the Vitis IDE Updated Step 4.
06/16/2021 Version 2021.1
Run-Time Ratio New topic.
Stream Data Types

Reading and Advancing an Input Stream

Writing and Advancing an Output Stream

New Stream types added.
Run-Time Parameter Support Summary AI Engine RTP Support table added.
Stream Switch FIFO


AI Engine Tile DMA Performance

New FIFO topics.
Packet Switching Graph Constructs Allowed number of packet streams updated.
Multicast Support New topic.
AI Engine/Programmable Logic Integration Updated content.
Hardware Emulation and Hardware Flows ADF_FRONTEND removed.
Performance Comparison Between AI Engine/PL and AI Engine/NoC Interfaces New topic.
AI Engine Compiler Options
  • Heap and Stack size updated.
  • --broadcast-enable-core CDO option added.
  • Tracing options updated.
  • xlopt updated.
Graph and Array Details New section added.
AI Engine Compiler Guidance New topic.
Reusing AI Engine Simulator Options --profile/AIE_PROFILE added to options.
Enabling Third-Party Simulators Simulators added and versions updated.
x86 Functional Simulator Updated content and new sections added.
Viewing the Run Summary in the Vitis Analyzer Content updated.
Trace View Data Visualization New section.
Run-Time Event API Performance Counters Usage Summary New topic.
Programming the PS Host Application ADF_FRONTEND removed.
Controlling the AI Engine Graph with the XRT C++ API New topic.
Error Reporting Through the XRT API xbutil scope updated.
Host Code Reference with ADF API and XRT API Updated for printf.
Clocking the PL Kernels Updated topic.
Compile the Embedded Application for the Cortex-A72 Processor Code updated.
  • aarch64-linux-gnu-g++ to aarch64-xilinx-linux-g++
Running Hardware Emulation New section.
Using the Vitis IDE Screenshot updates.
Mapper/Router Methodology New chapter.
Event API Removed extra Enumeration section.
FIFO Constraint New topic.
Using the Restrict Keyword in AI Engine Kernels Updated to C++.