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

Document ID: UG1393
Release Date: 2022-05-25
Version: 2022.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
Installing Embedded Platforms
Setting Up the Environment to Run the Vitis Software Platform
Introduction to the Vitis Environment for Acceleration
Accelerated Flow Application Development Using the Vitis Software Platform
FPGA Acceleration
Execution Model
Data Center Application Acceleration Development Flow
Embedded Processor Application Acceleration Development Flow
Build Targets
Tutorials and Examples
Introduction to Vitis Flows
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
Tutorials and Examples to Review
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
Summary and Next Steps
Developing Applications
Programming Model
Device Topology
PL Kernel Properties
SW-Controllable Kernels
Design Languages
HW Interfaces
Execution Modes
Non-Software Controlled Kernels
HW Interfaces
Clock and Reset Requirements
Host Programming
Specifying the Device ID and Loading the XCLBIN
Setting Up XRT-Managed Kernels and Kernel Arguments
Creating Multiple Compute Units
Transferring Data between Host and Kernels
Executing Kernels on the Device
Setting Up User-Managed Kernels and Argument Buffers
Summary
C/C++ Kernels
Process Execution Modes
Pipeline Execution
Auto-Restarting Mode
Data Types
Arbitrary Precision Integer Types
Arbitrary Precision Fixed-Point Data Types
Interfaces
Memory Mapped Interfaces
Kernel Interfaces
Memory Interface Width Considerations
Burst Accesses to Global Memory
Scalar Inputs
Streaming Interfaces
Loops
Loop Pipelining
Loop Unrolling
Loop Dependencies
Nested Loops
Sequential Loops
Dataflow Optimization
Dataflow Coding Example
Canonical Forms of Dataflow Optimization
Troubleshooting Dataflow
Array Configuration
Function Inlining
Auto-Restarting Kernels
Working with Auto-Restarting Kernels
Supported Kernel Interface
Enabling Auto-Restart
Using the Mailbox
Mailbox Semantics
Examples of Auto-Restarting Kernels
Scenario 1: Auto-Restarting Kernel with Streaming Interface
Scenario 2: Kernel Using Auto-Restart and Mailbox
Counted Auto-Restart
Summary
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
Adding C-Models to RTL Kernels
Design Recommendations for RTL Kernels
Memory Performance Optimizations for AXI4 Interface
Quality of Results Considerations
Debug and Verification Considerations
Versal AI Engine Programming
Best Practices for Data Center Acceleration with Vitis
Building and Running the Application
Setting Up the Vitis Environment
Build Targets
Software Emulation
Hardware Emulation
System Hardware Target
Building the Host Program
Compiling and Linking for x86
Compiling and Linking for Arm
Building the Device Binary
Compiling Kernels with the Vitis Compiler
Compiling Kernels with Vitis HLS
Creating Kernels in Vitis HLS
Vitis HLS Script for Creating Kernels
Linking the Kernels
Enabling Profile and Debug when Linking
Creating Multiple Instances of a Kernel
Mapping Kernel Ports to Memory
HBM Configuration and Use
Random Access and the RAMA IP
PLRAM Configuration and Use
Specifying Streaming Connections between Compute Units
Assigning Compute Units to SLRs
Managing Clock Frequencies
Identifying Platform Clocks
Managing Vivado Synthesis and Implementation Results
Using the -vivado and -advanced Options
Running Multiple Implementation Strategies for Timing Closure
Using -to_step and Launching Vivado Interactively
Controlling Report Generation
Packaging the System
Packaging for Embedded Platforms
Packaging for Data Center Platforms
Output Directories of the v++ Command
Running Emulation
Running Emulation Targets
Data Center vs. Embedded Platforms
QEMU
Running Emulation on Data Center Accelerator Cards
Running Emulation on an Embedded Processor Platform
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
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
Using I/O Traffic Generators
Adding Traffic Generators to Your Design
AXI4-Stream I/O Model for Streaming Traffic
Writing Traffic Generators in Python
Writing Traffic Generators in C++
Writing Traffic Generators in SV/Verilog
How to Use the create/use xtlm_ipc_verilog_stub Module
Manually Creating Sources for Mirror Modules
Manually Copying Generated Mirror Module into the User Project Directory
AXI4 Memory Map External Traffic through Python/C++
Use Cases
API/Pseudo Code
AXI4 Memory Map I/O Limitations in the Platform
XO Usage
Running Traffic Generators
Running the Application Hardware Build
Profiling, Optimizing, and Debugging the Application
Profiling the Application
Baselining Functionality and Performance
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
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 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
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
Optimizing the Performance
Host Optimization
Reducing Overhead of Kernel Enqueing
Optimizing Data Movement
Overlapping Data Transfers with Kernel Computation
Buffer Memory Segmentation
Compute Unit Scheduling
Multiple In-Order Command Queues
Single Out-of-Order Command Queue
Optimizing C++ Kernels
Optimizing Kernel Computation
Interface Attributes (Detailed Kernel Trace)
Using Burst Data Transfers
Using Full AXI Data Width
Optimizing Kernel to Kernel Communication
Optimizing Memory Architecture
Optimizing Computational Parallelism
Coding Data Parallelism
Loop Parallelism
Unrolling Loops
Pipelining Loops
Task Parallelism
Optimizing Device Resources
Exploring Kernel Optimizations Using Vitis HLS
Topological Optimization
Multiple Compute Units
Using Multiple DDR Banks
Assigning DDR Bank in Host Code
Assigning Global Memory for Kernel Code
Creating Multiple AXI Interfaces
Assigning AXI Interfaces to DDR Banks
Assigning AXI Interfaces to PLRAM
Kernel SLR and DDR Memory Assignments
Guidelines for Kernels that Access Multiple Memory Banks
Debugging Applications and Kernels
Debugging Flows
Debugging in Software Emulation
GDB-Based Debugging
Xilinx Runtime Library GDB Extensions
xprint Commands
xstatus Commands
GDB Kernel-Based Debugging
Command Line Debug Flow
Software Emulation Debug for Embedded Processors
Software Emulation Debug for Alveo Accelerators
Debugging OpenCL Kernels
Launching Host and Kernel Debug
Using printf() or cout to Debug Kernels
C/C++ Kernel
OpenCL Kernel
Debugging in Hardware Emulation
Waveform-Based Kernel Debugging
Enable Waveform Debugging with the Vitis Compiler Command
Run the Waveform-Based Kernel Debugging Flow
Debug Techniques for Hardware Emulation
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 Xilinx 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
Debugging on Embedded Processor Platforms
Emulation Debug for Embedded Processors
Hardware Debug for Embedded Processors
Example of Command Line Debugging
Vitis Environment Reference Materials
Vitis Compiler Command
Vitis Compiler General Options
--advanced Options
--clock Options
--connectivity Options
--debug 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
xbutil Utility
xbmgmt Utility
xclbinutil Utility
xclbin Information
Hardware Platform Information
Clocks
Memory Configuration
Kernel Information
Tool Generation Information
xrt.ini File
HLS Pragmas
Using the Vitis Analyzer
Working with Summary Reports
Configuring the Vitis Analyzer
Vitis Analyzer GUI and Window Manager
Diff Two Text Files
Compare Two Timeline Trace Reports
Cross-Probing between Reports
Using the Floating Ruler
Platform and System Diagrams
AI Engine Graphs and Arrays
Link Summary: Multiple Strategies and Timing Reports
Setting Guidance Thresholds
Creating an Archive File
Using the Vitis IDE
Launching Vitis IDE
Creating a Vitis IDE Project
Launch a Vitis IDE Workspace
Create an Application Project
Managing Platforms and Platform Repositories
Understanding the Vitis IDE
Adding Sources
Add Source Files
Create and Edit New Source Files
Working in the Project Editor View
Working in the Assistant View
Output Directories from the Vitis IDE
Building the System
Vitis IDE Guidance View
Working with Vivado Tools from the Vitis IDE
Vitis IDE Debug Flow
Using the Standalone Debug Flow
vitis -debug Command Line
Configuring the Vitis IDE
Vitis Project Settings
Vitis Build Configuration Settings
Vitis Hardware Function Settings
Vitis Binary Container Settings
Vitis Toolchain Settings
G++ Host Compiler and Linker Settings
V++ Compiler and Linker Settings
emconfigutil Settings
Vitis Run and Debug Configuration Settings
Project Export and Import
Export a Vitis Project
Import a Vitis Project
Import Projects from Git
Getting Started with Examples
Installing Examples and Libraries
Using Local Copies
RTL Kernel Wizard
Launch the RTL Kernel Wizard
Using the RTL Kernel Wizard
General Settings
Scalars
Global Memory
Streaming Interfaces
Summary
Using the RTL Kernel Project in Vivado IDE
RTL Type Kernel Project
Simulation Test Bench
Out-of-Context Synthesis
Software Model and Host Code Example
Generate RTL Kernel
Modifying an Existing RTL Kernel Generated from the Wizard
Using Vitis Embedded Platforms
Vitis Embedded Platforms
Introduction
Platform Types
Platform Naming Convention
Embedded Platform Components and Architecture
Installing Embedded Platforms
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
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
Run Baremetal Software Emulation
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
Software Emulation
Hardware Emulation
Profiling Execution on the Card
Profile Summary
Application Timeline
Hardware Event Tracing
PROFILE_KERNEL Examples
PROFILE_PORT Examples
Hardware Event Tracing Issues and Solutions
Supported Platforms and Startup Examples
Platforms
Start-Up Examples
Vitis C-Library Examples
Additional Information
Methodology for Accelerating Data Center Applications with the 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
OpenCL Programming
OpenCL Host Application
Setting Up the OpenCL Environment
Platform
Devices
Sub-Devices
Context
Command Queues
Program
Executing Commands in 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
Kernel Execution
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
Event Synchronization
Post-Processing and FPGA Cleanup
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
Streaming Data Transfers
Free-Running Kernel
Host Coding for Free-Running Kernels
Coding Guidelines for Free-Running Kernels
Additional Resources and Legal Notices
Xilinx Resources
Documentation Navigator and Design Hubs
Revision History
Please Read: Important Legal Notices

Back to home page