AI Engine Tools and Flows User Guide (UG1076) - 2025.2 English - Describes the AI Engine tools and flows. - UG1076

Document ID: UG1076
Release Date: 2025-11-20
Version: 2025.2 English

Overview
Navigating Content by Design Process
AI Engine Architecture Overview
AI Engine Components
Tools
Documentation
Compiling an AI Engine Graph Application
Setting Up the Vitis Tool Environment
Compiling using v++ (Unified Compiler)
v++ Mode AI Engine
AI Engine Options
CDO Options
Compiler Debugging Options
Design Rule Check Options
File Options
Module Specific Options
Event Tracing Options
Optimization Options
Miscellaneous Options
Macro for Device Architectures
AI Engine Compiler Guidance
Compiling AI Engine Graph for Independent Partitions
Simulating an AI Engine Graph Application
x86 Functional Simulator
Compiling the Design
Simulator Options
Data Snapshots
Deadlock Detection
Trace Report
Memory Access Violations and Valgrind
Using GDB
Macros
Printf() Macros
Using printf() in Kernels
Limitations
Memory Model
Graph API Calls
Preprocessor Considerations
Packet Switching and RTP
Packet Switching
Synchronous and Asynchronous RTP
Best Practices
Vitis Functional Simulation with AI Engine
AI Engine Simulator
Simulator Options
Simulation Input and Output Data Streams
TXT File Format
CSV File Format
Hang Detection
Memory Violations
Evaluating FIFO Depth To Break Deadlocks
Latency and Throughput Estimates
Hardware Emulation
External Traffic Generator
Performance Analysis of AI Engine Graph Application during Simulation
Analyzing AI Engine Status in Hardware Emulation
Generating and Analyzing AI Engine Status
AI Engine Simulation-Based Performance Analysis
AI Engine Simulation-Based Profiling
AI Engine Simulation-Based Value Change Dump
Generating a VCD File in the IDE
AI Engine Trace from VCD
Generating VCD with Select Signals
Using Vitis IDE to Generate a VCD with Select Signals
Viewing the Generated VCD in the Vitis Unified IDE
Viewing the Run Summary in the Vitis IDE
Trace View Data Visualization
Window Data Analysis
Buffer Data Types
Stream Data Analysis
Supported Stream Data Types
Cascade Data Analysis
Supported Cascade Data Types
Scalar RTP Data Analysis
Data Display Limitations
Cross Probing
Trace Compare
AI Engine Stall Analysis in the Vitis IDE
Performance Metrics
Lock Stall Analysis
Stream Stall Analysis
Cascade Stall Analysis
Memory Stall Analysis
DMA Stall Analysis
FIFO Depth Visualization in the Vitis IDE
DMA FIFO Depth Visualization
Stream Switch FIFO Visualization
Performance Analysis of AI Engine Graph Application on Hardware
Analyzing AI Engine Status in Hardware
Generating AI Engine Status
Analyzing AI Engine Status
Analyzing the Automated Status Output
Analyzing the Manual Status Output
Generating AI Engine Status using XSDB
Profiling the AI Engine
Profiling the AI Engine in Hardware
Profiling the AI Engine, Memory Modules and Interface Tiles
Profiling for AI Engine
Profiling for Memory Modules
Profiling Memory Tiles
Profiling for Interface Tiles
Metric Sets
Profiling Flows
XSDB Flow
XRT Flow
Viewing Profile Results in the Vitis IDE
Event Profile APIs for Graph Inputs and Outputs
Profiling Running Event and Graph Throughput
Profiling Graph Throughput
Profiling Graph Latency
Profiling Graph Bandwidth
Runtime Event API Performance Counters Usage Summary
XRT Support for Event APIs
Analysis of ADF Event API Profiling Flow vs. XRT-based Profiling Flow
Profiling the NoC
Introduction
Profiling the NMUs Connected to AI Engine
Profile Summary Report Analysis
Limitations
Event Tracing in Hardware
Event Trace Build Flow
Running the Design in Hardware and Capturing Trace Data at Run-Time
XSDB Flow
XRT Flow
Viewing and Analyzing the Trace Data in the Vitis IDE
Using the Delayed Event Trace
Using Multiple Event Trace Streams
Event Trace Offload using High Speed Debug Port
Trace Offload Methodology
Troubleshooting Event Trace in Hardware
Viewing Guidance in the Vitis IDE
Memory Tile Event Trace for AI Engine-ML-based Devices
DMA Event Trace in AI Engine-ML Tiles
Programming the PS Host Application
Host Programming on Linux
Controlling the Application with the XRT C++ API
Controlling Data Transfers between AI Engine and Global Memory
Controlling AI Engine Partitions
Memory Group for Buffer Object
Multi-Process and Multi-Thread Control of AI Engine Graphs
AI Engine Error Reporting
AI Engine Error Events
Compiling and Linking Host Code for Linux
Compiling and Linking Host Code with ADF API
Host Programming for Bare-Metal
Addressing Kernels in Bare-Metal Applications
Compiling and Linking Host Code for Bare-Metal
Host Programming Support Comparison Between Linux and Bare-Metal
AI Engine Graph API Methods
Runtime Control and Reload of AI Engine Partitions
Generate AI Engine-only and PL-only XCLBIN
Host Application for Runtime Reloading of AI Engine Partitions
Restrictions on AI Engine Partition Reloading
Mapper/Router Methodology
Design Convergence
Mapping Solution Not Found
Checking User-Defined Constraints
Reducing Window Buffer Sizes for Very High Memory Density Designs
Providing User Guidance to Mapper
Routing Solution Not Found
FIFO Depth Constraints
Area Group Constraints
Relative Constraints
Checking Mapping Results
Handling Large Designs
Event Trace Routing
Improving Design Performance
Memory Stalls
Stream Stalls
Large Skew between Identical Graph Outputs
Event Trace Reference
Simulation Event Trace
Hardware Event Trace
Event API
Enumeration
Member Functions
Encrypting AI Engine Kernels
Mapper/Router Design Rule Checks
AI Engine Test Harness
Additional Resources and Legal Notices
Finding Additional Documentation
Support Resources
References
Revision History
Please Read: Important Legal Notices

Back to home page