Revision History - 2024.2 English - UG1076

AI Engine Tools and Flows User Guide (UG1076)

Document ID
UG1076
Release Date
2024-11-28
Version
2024.2 English

The following table shows the revision history for this document.

Section Revision Summary
11/28/2024 Version 2024.2
General Update Removed references to classic AMD Vitis™ IDE, and AMD Vitis™ Analyzer because they were replaced by the AMD Vitis™ Unified IDE in 2024.2.
Moved the following sections to Vitis Reference Guide (UG1702):
  • Using the Vitis Unified IDE
  • Viewing Compilation Results in the Analysis View of the Vitis Unified IDE
Moved the following sections to Embedded Design Development Using Vitis (UG1701):
  • Hardware Emulation
  • AI Engine Hardware Profile and Debug Methodology
Removed Software Emulation because the feature is deprecated.
Compiling using v++ (Unified Compiler) Clarified the acceptable characters to use in file and directory names.
Event Tracing Options Removed deprecated event trace configuration values: functions, functions_partial_stalls, functions_all_stalls. Now, these values must be specified in the xrt.ini file for hardware emulation and run.
Compiling AI Engine Graph for Independent Partitions Clarified that the Analysis view of the Vitis Unified IDE can open only one partition compilation result at a time.
Data Snapshots
  • Added example of the configuration file contents ./Work/options/x86sim_dump.config that the compiler generates to specify what data to dump when running x86simulator --dump.
  • Added X86simulator dump configurations categories.
Latency and Throughput Estimates Updated right-click option labels available from the Latency Table in the Vitis IDE.
Profiling Memory Tiles Updated with additional metric name changes:
  • input_throughputs is now s2mm_throughputs.
  • output_throughputs is now mm2s_throughputs.
Generating AI Engine Status using XSDB
  • For the -aie-version option, updated the filename in path that contains the hw_gen value to aie_trace_config.json .
  • Updated the Tcl script to source the aie_status.
XSDB Flow Updated JSON file generated (-config-file <json-file>) to reflected per 2024.2 change.

Added options: -tile-based-aie-metrics <column|all>:<metric_set>, -tile-based-aie-metrics <mincolumn>:<maxcolumn>:<metric_set>.

Updated valid metrics:

  • Core and Memory modules: Added s2mm_throughputs and mm2s_throughputs; Removed read_throughputs and write_throughputs.
  • Interface tiles: Added input_stalls and output_stalls; Modified output_throughputs, and input_throughputs.
  • Memory tiles: Modified s2mm_channels_details and mm2s_channels_details; Added confict_stats1, conflict_stats2, conflict_stats3, and conflict_stats4.
Profiling for AI Engine Added the stream_put_get metric. Mentioned that s2mm_throughputs and mm2s_throughputs metrics are automatically selected to match the specified Memory Module metric sets.
Controlling Data Transfers between AI Engine and Global Memory Added information about external buffer objects, which is an alternative to GMIO objects for memory-mapped connections between global memory and the AI Enginegraph. Updated code example, and added code example.
Controlling AI Engine Partitions New topic that includes an example of code to control multiple partitions.
06/27/2024 Version 2024.1
General Updates Editorial updates only. No technical content updates.
05/30/2024 Version 2024.1
General Updates Deprecated the aiesimulator --end-wait-time option in 2024.1.
Renamed Event Trace Option metrics: functions_all_stalls changed to all_stalls, and functions_partial_stalls changed to partial_stalls.
Changed aiecompiler to v++ -c --mode aie per 2024.1 recommendation.
Setting Up the Vitis Tool Environment Added that the AI Engine tools require a license which can be generated for free from any eligible AMD licensing account.
Aiecompiler to Vitis Command Line Interface Migration Added that the --aiecompiler --export option is used to generate a aiecompiler.cfgconfiguration file.

Updated sample aiecompiler.cfg file.

Module Specific Options Specified that fast is the default value for --float-accuracy.
Miscellaneous Options Added the --swfifo-threshold option.
Compiling AI Engine Graph for Independent Partitions Provides details on AI Engine support of partitions.
Managing AI Engine Components with the Python Command Line Interface Clarified that you can use Python Command Line Interface (CLI) commands to automate the AI Engine component creation and build process in the Vitis IDE, and with a Python script.
Compiling the Design Removed support for the preprocessor directive in x86 simulator debug.
Enabling Third-Party Simulators in a Configuration File Updated configuration file settings for the release.
AI Engine Simulator Updated to support threads in the AI Engine multithreaded simulator.
Updated to show PLIO Average Throughput report generated in AI Engine simulation.
Simulator Options --hang-detect-time=<time in ns> option now supported in AI Engine-ML devices.
Reusing AI Engine Simulator Options
  • Updated to reflect that the --profile option is valid only for the AMD Vivado™ simulator.
  • Updated to reflect that to view the AMD Vivado™ simulator waveform GUI, use the launch_hw_emu script with -g option, and also use the -g option during the v++ --link stage as well.
  • Removed the AIE_Profile option because it is no longer supported for hardware emulation.
  • Added the AIE_PKG_DIR option to set the Work directory used by the AI Engine compiler.
Evaluating FIFO Depth To Break Deadlocks The --evaluate-fifo-depth option is available for AI Engine-ML designs.
Latency and Throughput Estimates Added new topic.
Exporting Summary Tables from the Analysis View New section added to explain how to export summary tables to a CSV file.
AI Engine Stall Analysis in the Vitis IDE Added note that a run summary file is generated for third-party simulators.
DMA Stall Analysis New section to explain how to configure and analyze DMA stalls.
Profiling for Memory Modules, Profiling Memory Tiles, Profiling for Interface Tiles, and Metric Sets Updated metric sets.
DMA Event Trace in AI Engine-ML Tiles New section to explain that DMA event tracing is available for AI Engine-ML tiles.
XRT Support for Event APIs New section that introduces XRT support for event profiling.
XRT Flow

Updated -graph-based-memory-tile-metrics to graph_based_memory_tile_metrics.

Updated -tile-based-memory-tile-metrics to tile_based_memory_tile_metrics.

Trace Offload Methodology, Event Tracing in Hardware, and Profiling the AI Engine in Hardware Added note regarding support on various BDC platforms.
Buffer Data Types Identified which data types are applicable to AI Engine and/or AI Engine-ML.
Handling Large Designs New section provides suggestions for handling large designs to alleviate placement challenges.
Event API Moved to UG1076 from UG1079 & UG1603.
12/04/2023 Version 2023.2
General Updates 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.
Compiling 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.
Evaluating 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 that 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.
Using Vitis IDE to Generate a VCD with Select Signals 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 the Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).
Debugging the AI Engine Application chapter Moved content to the 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 Updates 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 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.

Opening AI Engine Compilation Summary Reports 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 Data Transfers between AI Engine and Global Memory 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 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 Data Transfers between AI Engine and Global Memory 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
Opening AI Engine Compilation Summary Reports 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 Control of AI Engine Graphs 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.
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 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.
Buffer Data Types Updated data types.
Supported Stream Data Types
AI Engine Stall Analysis in the Vitis IDE New section.
Multi-Process and Multi-Thread Control of AI Engine Graphs 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.
Buffer 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++.