Installation - 2022.2 English

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

Document ID: UG1393
Release Date: 2022-12-07
Version: 2022.2 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 Vitis Flows
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
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
PL Kernel Properties
SW-Controllable Kernels
Design Languages
HW Interfaces
Execution Modes
Non-Software Controlled Kernels
HW Interfaces
Clock and Reset Requirements
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
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
Programming Versal AI Engines
Building and Running the Application
Setting Up the Vitis Environment
Build Targets
Software Emulation
Hardware Emulation
System Hardware Target
Building the Software Application
Compiling and Linking for x86
Compiling and Linking for Arm
Building the Device Binary
Compiling C/C++ PL Kernels
Compiling AI Engine Graph Applications
Linking the Kernels
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
Managing Vivado Synthesis and Implementation Results
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
Controlling Report Generation
Packaging the System
Packaging for Embedded Platforms
Packaging for Data Center Platforms
Running the Application
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
Running Emulation on an Embedded Processor Platform 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
AXI4-Stream I/O Model for Streaming Traffic through Python/C++/Verilog
Writing Traffic Generators in Python
Writing Traffic Generators in C++
Running Traffic Generators in Python/C++
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
AXI4 Memory Map External Traffic through Python/C++
Use Cases
API/Pseudo Code
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
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
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 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 Commands and Utilities
v++ Command
v++ General 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
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 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
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
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
Best Practices for Data Center Acceleration with Vitis
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 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
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
Assigning DDR Bank in Host Code
Assigning Global Memory for Kernel Code
Creating Multiple AXI Interfaces
Post-Processing and FPGA Cleanup
Streaming Data Transfers
Streaming Kernel Coding Guidelines
Free-Running Kernels
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
Output Structure of the Vitis Tools
Output Directories of the v++ Command
Output Directories from the Vitis IDE
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
Timeline Trace
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 Resources and Legal Notices
Xilinx Resources
Documentation Navigator and Design Hubs
Revision History
Please Read: Important Legal Notices

Back to home page