Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393) - 2024.1 English

Document ID: UG1393
Release Date: 2024-07-03
Version: 2024.1 English

Getting Started with Vitis
Navigating Content by Design Process
Vitis Software Platform Release Notes
What's New
Supported Platforms
Embedded GNU Toolchain Details
Changed Behavior
Known Issues
Installation
Installation Requirements
OpenCL Installable Client Driver Loader
Vitis Software Platform Installation
Installing the Vitis Software Platform
Installing Xilinx Runtime and Platforms
Setting Up the Environment to Run the Vitis Software Platform
Introduction to Vitis Flows
Introduction to the Vitis Unified IDE
Features
Components and System Projects
System Project Configuration Files
Migrating from Existing Tools
Terminology Changes
Control File Differences
Migrating Projects from Classic IDE
Introduction to Vitis Tools for Embedded System Designers
Terminology for Embedded System Design
Fixed Platforms versus Extensible Platforms
PS Software Development
Vitis PL Kernel Development Flow
Versal AI Engine Graph Development
Building and Packaging the System
Next Steps
Introduction to Data Center Acceleration for Software Programmers
Terminology
Working with Alveo Accelerator Cards
A Sample Application
Vitis Application Development Flow
Best Practices for Kernel Development
Best Practices for Host Programming
Next Steps
Introduction to Data Center Acceleration for RTL Designers
Terminology
Vitis Development Flow for RTL Designers
Using Alveo Accelerator Cards
Differences between Vivado and Vitis Development Flows
Creating and Packaging RTL Kernels
Building Kernels and Managing Implementation
Writing Host Applications with XRT API
Next Steps
Tutorials and Examples
Developing Applications
Programming Model
Design Topology
PL Kernel Properties
SW-Controllable Kernels
Design Languages
HW Interfaces
Execution Modes
Data Driven Kernels
HW Interfaces
Clock and Reset Requirements
Writing the Software Application
Specifying the Device ID and Loading the XCLBIN
Setting Up XRT-Managed Kernels and Kernel Arguments
Creating Multiple Compute Units
Transferring Data between Software and PL Kernels
Working with XRT-Managed Kernels
Working with User-Managed Kernels
Working with AI Engine Graphs
Summary
Developing PL Kernels using C++
Packaging RTL Kernels
Requirements of an RTL Kernel
Kernel Interface Requirements
Control Requirements for XRT-Managed Kernels
Interrupt
Creating User-Managed RTL Kernels
RTL Kernel Development Flow
Packaging the RTL Code as a Vitis XO
Design Recommendations for RTL Kernels
Memory Performance Optimizations for AXI4 Interface
Quality of Results Considerations
Debug and Verification Considerations
Programming Versal AI Engines
Building and Running the System
Setting Up the Vitis Environment
Working with Build Targets
Hardware Emulation
System Hardware Target
Building the Software Application
Compiling and Linking for x86
Compiling an Embedded Application for PS on x86
Compiling the Embedded Application for the Cortex-A72 Processor
Building the Device Binary
Compiling C/C++ PL Kernels
Compiling AI Engine Graph Applications
Deploying the AI Engine Graph
Iterative or Incremental AI Engine Application Compilation
Linking the System
Enabling Profile and Debug when Linking
Creating Multiple Instances of a Kernel
Mapping Kernel Ports to Memory
Additional Memory Mapping Techniques for Alveo Accelerator Cards
Assigning AXI Interfaces to PLRAM
HBM Configuration and Use
Random Access and the RAMA IP
Directly Accessing Host Memory on Alveo Accelerator Cards
Specifying Streaming Connections
Assigning Compute Units to SLRs on Alveo Accelerator Cards
SLR Guidelines for Kernels that Access Multiple Memory Banks
Managing Clock Frequencies
Identifying Platform Clocks
Syncing PL Clocks with the AI Engine
Controlling Report Generation
Managing Vivado Synthesis, Implementation, and Timing Closure
Working with Vivado in the Vitis Integrated Flow
Using the --vivado and --advanced Options
Associating an ELF file with MicroBlaze
Running Multiple Implementation Strategies for Timing Closure
Using --to_step and Launching Vivado Interactively
Vitis Export to Vivado Flow
Vitis Export Flow Guidelines and Limitations
Flow Details and Implementation
Packaging the System
Packaging for Embedded Platforms
Packaging Versal Designs
Packaging for Data Center Platforms
Packaging for DFX Platforms
Building a Bare-Metal System
Running the System on Hardware
Simulating the Application with the Emulation Flow
Running Emulation Targets
Data Center vs. Embedded Platforms
QEMU
Running Emulation on Data Center Accelerator Cards
Running Emulation on an Embedded Processor Platform
Embedded Processor Emulation Using PS on x86
Speed and Accuracy of Hardware Emulation
Working with Simulators in Hardware Emulation
Simulator Support
Using the Simulator Waveform Viewer
AXI Transactions Display in XSIM Waveform
Generating Test Vectors for Vitis HLS during Hardware Emulation
Working with Functional Model of the HLS Kernel
Working with SystemC Models
Coding a SystemC Model
Creating the XO
Linking with the v++ Command
Xilinx TLM – SystemC Library for ESL Modelling
Debug Techniques in Hardware Emulation
Working with I/O Traffic Generators
Adding Traffic Generators to Your Design
Using Traffic Generators for AI Engine Designs
Using Traffic Generators in AI Engine Graphs
AXI4-Stream I/O Model for Streaming Traffic
Writing Python Traffic Generators
Python API for AI Engine Graphs
Python API for PL Kernels
General Purpose Python API
Advanced Python Traffic Generator API
Writing Traffic Generators in MATLAB
MATLAB API for AI Engine Graphs
MATLAB API for PL Kernels
General Purpose MATLAB API
Writing Traffic Generators in C++
General Purpose C++ API
Advanced C++ Traffic Generator API
External RTL Traffic Generators using SV/Verilog
External RTL Traffic Generator and Emulation Process
External RTL Traffic Generator and AI Engine Simulation
Instantiating AI Engine Wrapper in the Test Bench
Generating sim_ipc_axis IP for Vivado Project
Running the RTL Traffic Generator with AI Engine Simulation
Running Traffic Generators in Python/C++/MATLAB
AXI4 Memory Map External Traffic through Python/C++
Use Cases
Writing Traffic Generators in C++
Writing Traffic Generators in Python
AXI4 Memory Map I/O Limitations in the Platform
XO Usage
Profiling and Debugging the Application
Profiling the Application
Enabling Profiling in Your Application
Continuous Trace Capture
Custom Profiling of the Host Application
Profiling of C++ Code
Profiling of C Code
Enabling Low Overhead Profiling
Enabling No Overhead Profiling
Enabling NoC-DDRMC Profiling
Guidance
Opening the Guidance Report
Interpreting Guidance Data
System Estimate Report
Opening the System Estimate Report
Interpreting the System Estimate Report
Design and Target Device Summary
Kernel Summary
Timing Information
Latency Information
Area Information
HLS Synthesis Report
Generating and Opening the HLS Report
Interpreting the HLS Report
Profile Summary Report
Generating and Opening the Profile Summary Report
Interpreting the Profile Summary
Timeline Trace
Generating and Opening the Timeline Trace
Interpreting the Timeline Trace
Detailed Kernel Trace
Using Burst Data Transfers
Using Full AXI Data Width
Waveform View and Live Waveform Viewer
Generating and Opening the Waveform Reports
Interpreting Data in the Waveform Views
Interpreting TLM Waveform Data for Third-Party Simulators
Debugging System Projects
Debugging in Hardware Emulation
Enable Waveform Debugging with the Vitis Compiler Command
Running Live Waveform Mode
Debug Techniques for Hardware Emulation
Hardware Emulation Debug from the Command Line
Debugging During Hardware Execution
Enabling Kernels for Debugging with Chipscope
Adding Debug IP to RTL Kernels
Enabling ILA Triggers for Hardware Debug
Adding ILA Triggers Before Starting Kernels
Pausing the Host Application Using GDB
Debugging with ChipScope
Checking the FPGA Board for Hardware Debug Support
Running XVC and HW Servers
Automated Setup for Hardware Debug
Manual Setup for Hardware Debug
Starting Debug Servers on an Amazon F1 Instance
Debugging Designs Using Vivado Hardware Manager
JTAG Fallback for Private Debug Network
JTAG Fallback Steps
Utilities for Hardware Debugging
Using the Linux dmesg Utility
Using the xbutil Utility
Techniques for Debugging Application Hangs
AXI Firewall Trips
Kernel Hangs Due to AXI Violations
Host Application Hangs When Accessing Memory
Typical Errors Leading to Application Hangs
Defensive Programming
Hardware Debug for Embedded Processors
Example of Command Line Debugging
Vitis Commands and Utilities
Launching the Vitis Unified IDE
Launch Options
v++ Command
v++ General Options
v++ Compilation Options
v++ General Compilation Options
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
v++ Mode HLS
HLS General Options
Array Partition Configuration
Array Stencil Configuration
C-Simulation Configuration
Co-Simulation Configuration
Compile Options
Dataflow Configuration
Debug Options
Interface Configuration
Package Options
Operator Configuration
RTL Configuration
Schedule Setting
Storage Configuration
Implementation Configuration
Unroll Setting
HLS Optimization Directives
syn.directive.aggregate
syn.directive.alias
syn.directive.allocation
syn.directive.array_partition
syn.directive.array_reshape
syn.directive.bind_op
syn.directive.bind_storage
syn.directive.dataflow
syn.directive.dependence
syn.directive.disaggregate
syn.directive.expression_balance
syn.directive.function_instantiate
syn.directive.inline
syn.directive.interface
syn.directive.latency
syn.directive.loop_flatten
syn.directive.loop_merge
syn.directive.loop_tripcount
syn.directive.occurrence
syn.directive.performance
syn.directive.pipeline
syn.directive.protocol
syn.directive.reset
syn.directive.stable
syn.directive.stream
syn.directive.top
syn.directive.unroll
HLS Pragmas
v++ Linking and Packaging Options
--advanced Options
--clock Options
--connectivity Options
--debug Options
--drc Options
--hls Options
--linkhook Options
--package Options
--profile Options
--vivado Options
Vitis Compiler Configuration File
Using the Message Rule File
emconfigutil Utility
kernelinfo Utility
Kernel Definition
Arguments
Ports
launch_emulator Utility
Versal PS and PMC Arguments for QEMU
Zynq UltraScale+ MPSoC PS and PMU Arguments for QEMU
Zynq 7000 PS Arguments for QEMU
manage_ipcache Utility
package_xo Command
RTL Kernel XML File
platforminfo Utility
Basic Platform Information
Hardware Platform Information
Interface Information
Clock Information
Valid SLRs
Resource Availability
Memory Information
Feature ROM Information
Software Platform Information
Platforminfo for xilinx_zcu104_base_202010_1
vitis-run Command
xbutil Utility
xbmgmt Utility
xclbinutil Utility
xclbin Information
Hardware Platform Information
Clocks
Memory Configuration
Kernel Information
Tool Generation Information
xrt.ini File
Using the Vitis Unified IDE
Launching Vitis Unified IDE
Working with the Vitis Unified IDE
Features of the Vitis Unified IDE
Using Vitis Component Explorer
Search View
Source Control
Launch Configurations
Debug View
Examples View
Repository Metadata
Managing Platform Repositories
Code View and Smart Editor Features
Preferences
Embedded Component Paths
Keyboard Shortcuts, Command Palette, and Quick Find
Jupyter Notebook Support
Parallel Compiling
Running Scripts in Batch Mode
Recreating a Workspace with Scripts
Scrollbar control tips
New Feature Preview
Creating an AI Engine Component
Creating an HLS Component
Creating an Application Component
Building the Application Component
Creating a System Project for Heterogeneous Computing
System Project Structure
Creating a System Project
Creating a System Project from Examples
Managing Components in System Projects
Defining the HW_Link System Configuration
Defining the Package Configuration
Building the System Project
Launching Run or Debug of the System Project
Debugging the System Project
Creating a Bare-metal System
Migrating Command-line Projects to the Vitis Unifed IDE
Debugging the System Project and AI Engine Components
Launching Debug in the Vitis Unified IDE
Using printf for Event Tracing
Hardware Emulation Debug from the Vitis IDE
Component Based Flow Design Debug
User Managed Flow Design Debug
Hardware Debug from the Vitis IDE
Component Based Flow Design Debug
User Managed Flow Design Debug
Using the Debug Environment
Watchpoints
Variable View and Memory Inspector
Register Inspector
Disassembly View
Multi-Kernel Debug
Viewing Data from Buffer Port Interfaces
Viewing Data from Stream Interfaces
AI Engine Pipeline View
Programming Device and Flash Memory
Vitis Interactive Python Shell
Auto-Completion of Python Statements
Basic Commands supported in Interactive mode
Python API: Managing Vitis IDE Components
Create and Build AI Engine Component
Create and Build HLS Component
Create and Build System Project
Create and Build Platform Component
Create and Build Application Component
Project Export and Import
Working with the Analysis View (Vitis Analyzer)
Configuring the Analysis View
Open Summary Reports
Exporting Summary Tables from the Analysis View
Analysis View Window Manager
Viewing AI Engine Graphs and Arrays
Importing JSON Output Files
Using Vitis Embedded Platforms
Vitis Embedded Platforms
Introduction
Platform Types
Platform Naming Convention
Embedded Platform Components and Architecture
Platform Clock Setting
Using Vitis Embedded Platforms
Packaging Images
Packaging Images with Ext4 rootfs in the Vitis IDE
Packaging Images with initramfs rootfs in the Vitis IDE
Writing Images to the SD Card
Configuring the PL Kernel in DFX Platforms and Non-DFX Platforms
Running an Acceleration Application on the Board
Software Package Management in PetaLinux rootfs
Creating Embedded Platforms in Vitis
Platform Creation Basics
Platforms
Platform Creation Requirements
Creating an Embedded Platform
Generate XSA file
CED Example Usage
Adding Hardware Interfaces
Updating Software Components
Packaging a Vitis Acceleration Platform
Testing Your Platform
Enabling Hardware Emulation for Extensible XSA
Special Considerations for Embedded Platform Creation
Validating an Embedded Platform
Check Platform Metadata
Use the Platform with Simple Test Case
Platform Hardware Design Validation
Additional Information
Accelerating Data Center Applications with Vitis Software Platform
Introduction
Acceleration: An Industrial Analogy
Methodology Overview
Recommendations
Methodology for Architecting a Device Accelerated Application
Step 1: Establish a Baseline Application Performance and Establish Goals
Measure Running Time
Measure Throughput
Determine the Maximum Achievable Throughput
Establish Overall Acceleration Goals
Step 2: Identify Functions to Accelerate
Identify Performance Bottlenecks
Identify Acceleration Potential
Step 3: Identify Device Parallelization Needs
Estimate Hardware Throughput without Parallelization
Determine How Much Parallelism is Needed
Determine How Many Samples the Datapath Should be Processing in Parallel
Determine How Many Kernels Can and Should be Instantiated in the Device
Step 4: Identify Software Application Parallelization Needs
Minimize CPU Idle Time While the Device Kernels are Running
Keep the Device Kernels Utilized
Optimize Data Transfers to and from the Device
Conceptualize the Desired Application Timeline
Step 5: Refine Architectural Details
Finalize Kernel Boundaries
Decide Kernel Placement and Connectivity
Methodology for Developing C/C++ Kernels
About the High-Level Synthesis Compiler
Verification Considerations
Step 1: Partition the Code into a Load-Compute-Store Pattern
Create a Top-Level Function with the Desired Interface
Code the Load and Store Functions
Match Port Width to Datapath Width
Use Burst Transfers
Minimize the Number of Data Transfers from Global Memory
Code the Compute Functions
Connect the Load, Compute, and Store Functions
Step 2: Partition the Compute Blocks into Smaller Functions
Decompose to Identify Throughput Goals
Aim for Functions with a Single Loop Nest
Connect Compute Functions Using the Dataflow ‘Canonical Form’
Step 3: Identify Loops Requiring Optimization
Step 4: Improve Loop Latencies
Apply Loop Unrolling
Apply Array Partitioning
Step 5: Improve Loop Throughput
Eliminate I/O Contentions
Eliminate Loop-Carried Dependencies
Advanced Techniques
Best Practices for Data Center Acceleration with Vitis
Migrating to a New Target Platform
Design Migration
Understanding an FPGA Architecture
Understanding Target Platforms
Migrating Releases
Host Code Migration
Release Migration
Modifying Kernel Placement
Implications of a New Hardware Platform
Determining Where to Place the Kernels
Assigning Kernels to SLRs
Address Timing
Custom Constraints
Timing Closure Considerations
OpenCL Programming
OpenCL Host Application
OpenCL Installable Client Driver Loader
Setting Up the OpenCL Environment
Platform
Devices
Sub-Devices
Context
Command Queues
Program
Executing Commands on the FPGA
Setting Up Kernels
Setting Kernel Arguments
Buffer Allocation on the Device
Buffer Creation and Data Transfer
Letting XRT Allocate Buffers
Using Host Pointer Buffers
Allocating Page-Aligned Host Memory
Sub-Buffers
Reading a Specific Portion from the Device Buffer
Device Buffer Shared by Multiple Memory Ports or Multiple Kernels
Optimizing Data Movement
Overlapping Data Transfers with Kernel Computation
Buffer Memory Segmentation
Kernel Execution
Reducing Overhead of Kernel Enqueing
Task Parallelism Using Different Kernels
Spatial Data Parallelism: Increase Number of Compute Units
Temporal Data Parallelism: Host-to-Kernel Dataflow
Enabling Host-to-Kernel Dataflow
Symmetrical and Asymmetrical Compute Units
Kernel Handle and Compute Units
Using Compute Unit Name to Get Handle of All Asymmetrical Compute Units
Compute Unit Scheduling
Multiple In-Order Command Queues
Single Out-of-Order Command Queue
Event Synchronization
Debugging OpenCL Kernels
Using printf() to Debug OpenCL Kernel
Assigning DDR Bank in Host Code
Assigning Global Memory for Kernel Code
Creating Multiple AXI Interfaces
Post-Processing and FPGA Cleanup
Compiling and Linking the Host Application
Output Structure of the Vitis Tools
Output Directories of the v++ Command
Output Directories of v++ -c --mode aie
Output Directories of v++ -c --mode hls
Output Directories of the Vitis Unified IDE
Python XSDB Commands
Breakpoints
Connections
Device
Download
IPI
JTAG
Memory
Miscellaneous
Registers
Reset
Running
STAPL
Streams
SVF
TFile
Usage Examples
Streaming Data Transfers
Streaming Kernel Coding Guidelines
Free-Running Kernels
Using Vitis System Compilation Mode
Introduction to Vitis System Compilation Mode
Terminology
Hardware and Software Organization
Design Capture and Modeling
Quick Start Example
Modeling the Convolution Filter
Hardware System Architecture
Host Side Data Generation
Creating a VSC Makefile
Environment Setup
Using the Template Makefile
Writing a Custom Makefile
OS and Tool-Chain Compatibility
Building Hardware
Accelerator HW Interface
User-Defined Accelerator Class
Guidance Macros
The compute() API
Interface Data Types
Platform Specific Hardware Config
Accelerator System Composition
Stream connections using vpp::stream
Single-path Synchronous Pipeline
Free-Running PE
Streaming Network of PEs
Data Transfer Interface Considerations
Application Software Interface
Host Code Organization
VPP_ACC Class API
Special Data Transfer Models
Accelerator Execution Models
Asynchronous Host Control of Accelerator
CU Cluster and Multi-Card Support
Multi-Accelerator Pipeline Composition
Interoperability with XO and RTL Kernels
Passing Buffer from XO Kernel to VPP_ACC
Passing a Buffer from VPP_ACC to XO Kernel
Debugging and Validation
Hardware Emulation
Profiling Execution on the Card
Profile Summary
Timeline Trace
Hardware Event Tracing
PROFILE_KERNEL Examples
PROFILE_PORT Examples
Hardware Event Tracing Issues and Solutions
Supported Platforms and Startup Examples
Platforms
Vitis C-Library Examples
Additional Resources and Legal Notices
Finding Additional Documentation
Support Resources
Revision History
Please Read: Important Legal Notices

Back to home page