Revision History - 2022.1 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)

Document ID

UG1076

Release Date

2022-05-25

Version

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.
XSDB Flow 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.
input_gmio/output_gmio input_plio/output_plio	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	Updated 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 DMA 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++.