Revision History - 2023.2 English

AI Engine Tools and Flows User Guide (UG1076)

Document ID
UG1076
Release Date
2023-12-04
Version
2023.2 English

The following table shows the revision history for this document.

Section Revision Summary
12/04/2023 Version 2023.2
General Continued to update to reflect the usage of the new unified AMD Vitis™ IDE.
Simulator Options Added --dump-size=SIZE option.
AI Engine Compiler Options Added more details about the pl-register-threshold option.
Inline Keywords Added details about theinline keyword.
FIFO Depth Evaluation Added content about FIFO depth evaluation.
Compiling and Linking Host Code with ADF API Added new section.
AI Engine Simulation-Based Profiling Further defined information generated in the Function Reports section of the Profile report.
10/18/2023 Version 2023.2
Throughout the document Updated to reflect the usage of the new unifiedAMD Vitis™ IDE.
Updated to reflect AI Engine-ML support.
Migration to Vitis Unified IDE Added information about migrating 2023.1 command-line projects to unified Vitis IDE, and migrating 2023.1 Vitis Classic IDE projects to Vitis Unified IDE.
Using the Vitis Unified IDE Added information on how to create AI Engine components, and simulate and debug them in the new unified Vitis IDE.
AI Engine Compiler Options Added --part, -runtime-opt, --float-accuracy arg, --lock-fence-mode, and --evaluate-fifo-depth options.
Mapper and Router Options Added disableMultiDMAFifo and skipUnroutableTraceNets options.
Macro for Device Architectures Added __AIE_ARCH__ macro details.
Compile using v++ (Unified Compiler) Updated to reflect the usage of the new unifiedVitis command line AI Engine compiler.
Simulation Input and Output Data Streams, and CSV File Format Added support for CSV file format for PLIO inputs and outputs.
Evaluate FIFO Depth To Break Deadlocks Added information on how to use the FIFO Depth Report from the aiesimulator to alleviate deadlocks.
Reusing AI Engine Simulator Options Clarified that the AIE_Profile option is not supported for third-party simulators.
Inputs Added note: the main function must have a return statement. Otherwise, aiecompiler will error out.
Simulator Options Added --dump_size x86simulator option.
Memory Tile Event Trace for AI Engine-ML-based Devices Added event trace details of memory tiles for AI Engine-ML based applications.
Profiling Memory Tiles Added profiling details of memory tiles for AI Engine-ML based applications.
AI Engine Trace from VCD Updated the directory path of the generated event trace data.
Generating VCD with Select Signals Added row, column and time window options in the options.txt file which are used to generate the VCD.
Generating a VCD with Select Signals in the IDE Added information on how to use the Vitis Unified IDE to specify row, column and time window options which are used to generate the VCD.
Profiling the NoC Added information on how to monitor network performance on the NoC.
XSDB Flow Updated table to reflect profiling options for memory tiles. Added multi-level hierarchy graph support for interface tile metrics.
XRT Flow Updated table to reflect profiling options for memory tiles. Added multi-level hierarchy graph support for interface tile metrics.
XSDB Flow Updated multi-level hierarchy graph support example.
XRT Flow Removed the offload_interval_us, and file_dump_interval_s options.

Added multi-level hierarchy graph support example.

Viewing Profile Results in the Vitis IDE Added the new Performance Annotation in Graph View section.
Event Trace Offload using High Speed Debug Port Added information in support of using high speed debug port to offload trace data.
Event Trace Routing Added information on how to handle event trace routing failures.
Integrating the Application Using the Vitis Tools Flow chapter Moved content to Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).
Debugging the AI Engine Application chapter Moved content to Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).
06/23/2023 Version 2023.1
Simulating an AI Engine Graph Application, and Performance Analysis of AI Engine Graph Application on Hardware Added tip regarding the precompiled AI Engine test harness, with link to GitHub for more information.
Compiling the Embedded Application for the x86 Processor Added note to set the GCC path from the AMD Vitis™ Install.
05/16/2023 Version 2023.1
General Update screen captures to reflect the new Vitis IDE to view compilation and simulation reports, and summary files.
Added the-a option for launching Vitis Analyzer with a summary file, as in, vitis_analyzer -a throughout the document.
Moved "Using the Restrict Keyword in AI Engine Kernels" and "Non-Templated Versions of Window and Stream APIs" appendixes to AI Engine Kernel and Graph Programming Guide (UG1079).
Updated window to buffer, as in input_window to input_buffer< and output_window to output_buffer.
Tools Added new Vitis IDE to view compilation and simulation reports, and analyze output files generated by the AI Engine compiler. Added Vitis unified command line interface.
AI Engine Compiler Options Added --graph-iterator-event event trace compiler option.

Added --evaluate-fifo-depth miscellaneous option that helps to avoid the manual and iterative process of adding FIFO depth. When the design is compiled with this option and simulated using aiesimulator, FIFO depth recommendations are generated by the simulator.

Viewing Compilation Results in the Analysis View of the Vitis Unified IDE Updated examples, and screen captures in this section to reflect the new Vitis IDE.
Simulating an AI Engine Graph Application Updated Simulation Flows, Simulation Models, and Simulation Features tables.
Simulator Options Updated description for --display-run-interval=<time in ns>,--dump-vcd=<file>, --enable-handshake-ext-tb, --enable-memory-check, --hang-detect-time=<time in ns>, and --online.
Simulator Options

Added the --options-file option to specify the text file for selective VCD.

Generating VCD with Select Signals New section on generating AI Engine selective VCD modules.
External Traffic Generator Added new section.
Reusing AI Engine Simulator Options Added information about viewing the run summary.
Trace Compare Added recommendation to use vitis_analyzer --classic for the trace compare feature.
Stream Switch FIFO Visualization New section on data visualization of stream switch FIFOs.
Profiling the AI Engine, Memory Modules and Interface Tiles and Profiling Flows Updated bandwidth with throughput.
XSDB Flow Added -start-type, -start-time, and -start-iteration options, and examples.

Renamed -tile_based_aie_tile_metrics to -tile-based-aie-tile-metrics , -graph_based_aie_tile_metrics to -graph-based-aie-tile-metrics , and -tile_based_interface_tile_metrics to -tile-based-interface-tile-metrics.

XRT Flow Added start_type, start_time, and start_iteration options, and examples.
Using the Delayed Event Trace New section.
FIFO Depth Visualization in the Vitis IDE Added section for data visualization of stream switch FIFOs.
Analyzing AI Engine Status Added note that mentions that you can access error events in classic Vitis Analyzer with vitis_analyzer --classic, and not in the new Vitis IDE Analysis view.
Troubleshooting Event Trace in Hardware Updated -config-level to use -graph-based-aie-tile-metrics in example, because -config-level is no longer supported.
Programming the PS Host Application Removed references to ADF APIs, and updated to use XRT API only.
Controlling the Application with the XRT C++ API Updated the execution model for the XRT API controlling PL kernels and AI Engine graphs, and updated example code.
Controlling AI Engine GMIO Transfers Added note that only non-cacheable buffers are supported for AI Engine GMIO buffers.
Compiling and Linking Host Code for Linux New section.
Compiling and Linking Host Code for Bare-Metal New section.
Resetting and Reloading Flow of the AI Engine Array New section.
Platforms Updated Types of Platforms.
Compiling the Embedded Application for the Cortex-A72 Processor Updated for XRT-only compile.
Resetting and Reloading Flow of the AI Engine Array Added new section.
Introduction to the new Vitis Unified IDE Added new appendix to introduce the preview mode tool.
10/05/2022 Version 2022.2
Document title Changed title to AI Engine Tools and Flows User Guide.
Throughout the document Moved graph programming content to AI Engine Kernel and Graph Programming Guide (UG1079).
AI Engine Compiler Options Added DRC Options. Updated Event Trace options.
Simulation Input and Output Data Streams Added simulation option file details.
Enabling Third-Party Simulators in a Configuration File Updated v++ --link Configuration to use generic <SIMULATOR DIRECTORY> variable.
Scalar RTP Data Analysis New topic.
Profiling Graph Latency Added example code for hardware and hardware emulation flows.
Profiling for AI Engine Removed stream_put_get Metric.
XSDB Flow Added XSDB Trace options.
Limitations New topic.
Memory Model Added explanation of the macro X86SIM_THREAD_LOCALto make the global read/write thread safe.
Profiling for Interface Tiles Updated input_bandwidths and output_bandwidths metrics. New packets metrics.
XSDB Flow Updated and added new aieprofile options.
XRT Flow, andXRT Flow Updated xrt.ini options, and examples throughout.
Troubleshooting Event Trace in Hardware Updated troubleshooting options for when trace packets are being dropped on certain streams.
Controlling AI Engine GMIO Transfers New topic.
Iterative AI Engine Application Compilation New topic.
Viewing Data from Buffer Port Interfaces New topic.
Linking the System Added sp Connectivity Section Options
Analyzing AI Engine Status in Hardware Emulation New topic to describe Vitis Analyzer support for AI Engine profile and status in hardware emulation.
Compiling the Embedded Application for the x86 Processor New topic to describe support for PS on x86 flow in software emulation.
Creating Traffic Generators using System Verilog/Verilog New topic to describe how to use Verilog or System Verilog modules/testbenches to drive traffic in and out of an ADF graph running in the AI Engine Simulator.
Encrypting AI Engine Kernels New appendix, which refers to Encryption web lounge for more details.
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 Analysis View of the Vitis Unified IDE Updated graphs for the 2022.1 release.
I/O, 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 in the Vitis IDE Added this guidance.
Using Traffic Generators for AI Engine System Projects 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.
Chapter 12: 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 in a Configuration File 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 the Vitis IDE 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 Profile Results in the Vitis IDE 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

Added ability to report out AI Engine status in hardware, and added ability to open and analyze the report in Vitis Analyzer.
Packaging for DFX Platforms 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.
Using Traffic Generators for AI Engine Systems

Using Traffic Generators in AI Engine Graphs

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 for Hardware

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
Chapter 8: 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 11
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 Components Updated.
Prepare the Kernels Updated for AI Engine API.
Creating a Data Flow Graph (Including Kernels) Figure representing graph connectivity added.
Chapter 8: Window and Streaming Data API Updated data types for AI Engine API and template support.
Packet Swithching 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 the Vitis IDE 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.
Chapter 11: 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 in a Configuration File Simulators added and versions updated.
x86 Functional Simulator Updated content and new sections added.
Viewing the Run Summary in the Vitis IDE 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 Application with the XRT C++ API New topic.
AI Engine Error Reporting xbutil scope updated.
Host Code Reference with ADF API and XRT API Updated for printf.
Syncing Clocks with the AI Engine Updated topic.
Compiling 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++.