Introduction - 2023.1 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID: UG1399
Release Date: 2023-07-17
Version: 2023.1 English

Introduction
Navigating Content by Design Process
Supported Operating Systems for Vitis HLS
Benefits of High-Level Synthesis
Introduction to Vitis HLS
Re-Architecting the Design Code
Introduction to the new Vitis Unified IDE
Tutorials and Examples
HLS Programmers Guide
Design Principles
Three Paradigms for Programming FPGAs
Producer-Consumer Paradigm
Streaming Data Paradigm
Pipelining Paradigm
Combining the Three Paradigms
Conclusion - A Prescription for Performance
Abstract Parallel Programming Model for HLS
Control and Data Driven Tasks
Data-driven Task-level Parallelism
Control-driven Task-level Parallelism
Canonical Forms
Canonical Body
Dataflow Checking
Configuring Dataflow Memory Channels
Specifying Arrays as PIPOs or FIFOs
Specifying Arrays as Stream-of-Blocks
Specifying Compiler-Created FIFO Depth
Stable Arrays
Mixing Data-Driven and Control-Driven Models
Summary
Loops Primer
Pipelining Loops
Automatic Loop Pipelining
Rewinding Pipelined Loops for Performance
Flushing Pipelines and Pipeline Types
Managing Pipeline Dependencies
Unrolling Loops
Merging Loops
Working with Nested Loops
Working with Variable Loop Bounds
Arrays Primer
Mapping Software Arrays to Hardware Memory
Array Accesses and Performance
Array Partitioning
Automatic Array Partitioning
Array Reshaping
Arrays on the Interface
Array Interfaces
FIFO Interfaces
Memory Mapped Interfaces
Initializing and Resetting Arrays
Implementing ROMs
C Simulation with Arrays
Functions Primer
Function Inlining
Function Pipelining
Function Instantiation
Data Types
Standard Types
Floats and Doubles
Composite Data Types
Structs
Structs in the Interface
Struct Padding and Alignment
C++ Classes and Templates
Global Variables and Classes
Templates
Using Templates to Create Unique Instances
Enumerated Types
Unions
Type Qualifiers
Volatile
Statics
Const
ROM Optimization
Arbitrary Precision (AP) Data Types
Advantages of AP Data Types
Overview of Arbitrary Precision Integer Data Types
Overview of Arbitrary Precision Fixed-Point Data Types
Global Variables
Pointers
Pointers on the Interface
Basic Pointers
Pointer Arithmetic
Multi-Access Pointers on the Interface
Understanding Volatile Data
Modeling Streaming Data Interfaces
Multi-Access Pointers and RTL Simulation
Vector Data Types
Bit-Width Propagation
Unsupported C/C++ Constructs
System Calls
Dynamic Memory Usage
Pointer Limitations
Recursive Functions
Standard Template Libraries
Undefined Behaviors
Virtual Functions and Pointers
Interfaces of the HLS Design
Defining Interfaces
Introduction to Interface Synthesis
Interfaces for Vitis Kernel Flow
Interfaces for Vivado IP Flow
AXI Adapter Interface Protocols
AXI4 Master Interface
Offset and Modes of Operation
Controlling the Address Offset in an AXI4 Interface
M_AXI Bundles
M_AXI Channels
M_AXI Resources
Controlling AXI4 Burst Behavior
Automatic Port Width Resizing
Creating an AXI4 Interface with 32-bit Address
Customizing AXI4 Master Interfaces in IP Integrator
AXI4-Lite Interface
S_AXILITE Example
S_AXILITE Control Register Map
S_AXILITE and Port-Level Protocols
S_AXILITE Bundle Rules
S_AXILITE Offset Option
C Driver Files
C Driver Files and Float Types
Controlling Hardware
Controlling Software
Control Clock and Reset in AXI4-Lite Interfaces
Customizing AXI4-Lite Slave Interfaces in IP Integrator
AXI4-Stream Interfaces
How AXI4-Stream Works
How AXI4-Stream is Implemented
Registered AXI4-Stream Interfaces
AXI4-Stream Interfaces without Side-Channels
AXI4-Stream Interfaces with Side-Channels
Coding Style for Array to Stream
Port-Level Protocols for Vivado IP Flow
Port-Level I/O: No Protocol
Port-Level I/O: Wire Handshakes
Port-Level I/O: Memory Interface Protocol
Programming Model for Multi-Port Access in HBM
Managing Interfaces with SSI Technology Devices
Vitis HLS Memory Layout Model
Data Alignment
Data Structure Padding
Vitis HLS Alignment Rules and Semantics
Examples of Aggregation
Examples of Disaggregation
Impact of Struct Size on Pipelining
Execution Modes of HLS Designs
Block-Level Control Protocols
Auto-Restarting Mode
Working with Auto-Restarting Designs
Supported Interfaces
Enabling Auto-Restart
Using the Mailbox
Mailbox Semantics
Examples of Auto-Restarting Designs
Using Auto-Restart with the Mailbox
Using Counted Auto-Restart
Controlling Initialization and Reset Behavior
Initialization Behavior
Best Practices for Designing with M_AXI Interfaces
Optimizing Techniques and Troubleshooting Tips
Understanding High-Level Synthesis Scheduling and Binding
Scheduling and Binding Example
Extracting Control Logic and Implementing I/O Ports Example
Performance Metrics Example
Optimizing Logic
Inferring Shift Registers
Optimizing Logic Expressions
Optimizing AXI System Performance
AXI Burst Transfers
Preconditions and Limitations of Burst Transfer
Options for Controlling AXI4 Burst Behavior
Examples of Recommended Coding Styles
Summary
Using Manual Burst
AXI Performance Case Study
Managing Area and Hardware Resources
Limiting the Number of Operators
Controlling Hardware Implementation
Controlling Operator Pipelining
Unrolling Loops in C++ Classes
Limitations of Control-Driven Task-Level Parallelism
Limitations of Pipelining with Static Variables
Using Vitis HLS
Launching Vitis HLS
Setting Up the Environment
Overview of the Vitis HLS IDE
Customizing the Vitis HLS IDE Behavior
Creating a New Vitis HLS Project
Vitis HLS Flow Overview
Enabling the Vivado IP Flow
Enabling the Vitis Kernel Flow
Default Settings of Vivado/Vitis Flows
Working with Sources
Coding C/C++ Functions
Accessing Source Files in Git Repositories
Using Libraries in Vitis HLS
Resolving References and Viewing #include Files
Resolving Comments in the Source Code
Adding RTL Blackbox Functions
Using the RTL Blackbox Wizard
C++ Model and Header Files
RTL IP Definition
JSON File for RTL Blackbox
Setting Configuration Options
Specifying the Clock Frequency
Clock and Reset Ports
Using the Flow Navigator
Verifying Code with C Simulation
Writing a Test Bench
Example Test Bench
Design Files and Test Bench Files
Single File Test Bench and Design
Using the Debug View Layout
Output of C Simulation
Pre-Synthesis Control Flow
Synthesizing the Code
Synthesis Summary
Output of C Synthesis
Improving Synthesis Runtime and Capacity
Analyzing the Results of Synthesis
Schedule Viewer
Function Call Graph Viewer
Dataflow Viewer
Optimizing the HLS Project
Creating Additional Solutions
Adding Pragmas and Directives
Using Directives in Scripts vs. Pragmas in Code
Applying Directives to the Proper Scope
Applying Optimization Directives to Global Variables
Applying Optimization Directives to Class Objects
Applying Optimization Directives to Templates
Using Constants with Pragmas
Failure to Satisfy Optimization Directives
C/RTL Co-Simulation in Vitis HLS
Output of C/RTL Co-Simulation
Automatically Verifying the RTL
Interface Synthesis Requirements
Verification of DATAFLOW and DEPENDENCE
Unsupported Optimizations for Co-Simulation
Simulating IP Cores
Analyzing RTL Simulations
Viewing Simulation Waveforms
Cosim Deadlock Viewer
Timeline Trace Viewer
Debugging C/RTL Co-Simulation
Setting Up the Environment
Optimization Directives
C Test Bench and C Source Code
Exporting the RTL Design
Running Implementation
Implementation Report
Output of RTL Export
Archiving the Project
Running Vitis HLS from the Command Line
Vitis HLS Command Reference
vitis_hls Command
hls_init.tcl
Project Commands
add_files
cat_ini
close_project
close_solution
cosim_design
cosim_stall
create_clock
csim_design
csynth_design
delete_project
delete_solution
enable_beta_device
export_design
get_clock_period
get_clock_uncertainty
get_files
get_part
get_project
get_solution
get_top
help
list_part
open_project
open_solution
open_tcl_project
set_clock_uncertainty
set_part
set_top
write_ini
Configuration Commands
config_array_partition
config_compile
config_cosim
config_csim
config_dataflow
config_debug
config_export
config_interface
config_op
config_rtl
config_schedule
config_storage
config_unroll
Optimization Directives
set_directive_aggregate
set_directive_alias
set_directive_allocation
set_directive_array_partition
set_directive_array_reshape
set_directive_bind_op
set_directive_bind_storage
set_directive_dataflow
set_directive_dependence
set_directive_disaggregate
set_directive_expression_balance
set_directive_function_instantiate
set_directive_inline
set_directive_interface
set_directive_latency
set_directive_loop_flatten
set_directive_loop_merge
set_directive_loop_tripcount
set_directive_occurrence
set_directive_performance
set_directive_pipeline
set_directive_protocol
set_directive_reset
set_directive_stable
set_directive_stream
set_directive_top
set_directive_unroll
HLS Pragmas
pragma HLS aggregate
pragma HLS alias
pragma HLS allocation
pragma HLS array_partition
pragma HLS array_reshape
pragma HLS bind_op
pragma HLS bind_storage
pragma HLS dataflow
pragma HLS dependence
pragma HLS disaggregate
pragma HLS expression_balance
pragma HLS function_instantiate
pragma HLS inline
pragma HLS interface
pragma HLS latency
pragma HLS loop_flatten
pragma HLS loop_merge
pragma HLS loop_tripcount
pragma HLS occurrence
pragma HLS performance
pragma HLS pipeline
pragma HLS protocol
pragma HLS reset
pragma HLS stable
pragma HLS stream
pragma HLS top
pragma HLS unroll
Vitis HLS C Driver Reference
AXI4-Lite Slave C Driver Reference
X<DUT>_Initialize
X<DUT>_CfgInitialize
X<DUT>_LookupConfig
X<DUT>_Release
X<DUT>_Start
X<DUT>_IsDone
X<DUT>_IsIdle
X<DUT>_IsReady
X<DUT>_Continue
X<DUT>_EnableAutoRestart
X<DUT>_DisableAutoRestart
X<DUT>_Set_ARG
X<DUT>_Set_ARG_vld
X<DUT>_Set_ARG_ack
X<DUT>_Get_ARG
X<DUT>_Get_ARG_vld
X<DUT>_Get_ARG_ack
X<DUT>_Get_ARG_BaseAddress
X<DUT>_Get_ARG_HighAddress
X<DUT>_Get_ARG_TotalBytes
X<DUT>_Get_ARG_BitWidth
X<DUT>_Get_ARG_Depth
X<DUT>_Write_ARG_Words
X<DUT>_Read_ARG_Words
X<DUT>_Write_ARG_Bytes
X<DUT>_Read_ARG_Bytes
X<DUT>_InterruptGlobalEnable
X<DUT>_InterruptGlobalDisable
X<DUT>_InterruptEnable
X<DUT>_InterruptDisable
X<DUT>_InterruptClear
X<DUT>_InterruptGetEnabled
X<DUT>_InterruptGetStatus
Vitis HLS Libraries Reference
C/C++ Builtin Functions
Arbitrary Precision Data Types Library
Using Arbitrary Precision Data Types
Arbitrary Integer Precision Types with C++
Arbitrary Precision Fixed-Point Data Types
Fixed-Point Identifier Summary
Example Using ap_fixed
C++ Arbitrary Precision Integer Types
C++ Arbitrary Precision Integer Types: Reference Information
C++ Arbitrary Precision Types
Compiling ap_[u]int<> Types
Declaring/Defining ap_[u] Variables
Initialization and Assignment from Constants (Literals)
Support for Console I/O (Printing)
Expressions Involving ap_[u]<> types
Class Methods and Operators
Other Class Methods, Operators, and Data Members
C++ Arbitrary Precision Fixed-Point Types
Fixed-Point Identifier Summary
C++ Arbitrary Precision Fixed-Point Types: Reference Information
C++ Arbitrary Precision Fixed-Point Types
ap_[u]fixed Representation
Quantization Modes
Overflow Modes
Compiling ap_[u]fixed<> Types
Declaring and Defining ap_[u]fixed<> Variables
Initialization and Assignment from Constants (Literals)
Support for Console I/O (Printing)
Expressions Involving ap_[u]fixed<> types
Class Methods, Operators, and Data Members
HLS Print Function
HLS Math Library
HLS Math Library Accuracy
HLS Math Library
Fixed-Point Math Functions
Verification and Math Functions
Verification Option 1: Standard Math Library and Verify Differences
Verification Option 2: HLS Math Library and Validate Differences
Verification Option 3: HLS Math Library File and Validate Differences
Common Synthesis Errors
HLS Stream Library
C Modeling and RTL Implementation
Using HLS Streams
Blocking API
Blocking Write Methods
Blocking Read Methods
Deterministic Behavior
Non-Blocking API
Non-Blocking Write
Non-Blocking Read
hls::stream.capacity() Method
hls::stream.empty() Method
hls::stream.full() Method
hls::stream.size() Method
Controlling the RTL FIFO Depth
HLS Vector Library
HLS Task Library
Tasks and Channels
Tasks and Dataflow
HLS Split/Merge Library
HLS Stream of Blocks Library
Stream-of-Blocks Modeling Style
Resource Usage
Checking for Full and Empty Blocks
Modeling Feedback in Dataflow Regions
Limitations
HLS IP Libraries
FFT IP Library
FFT Static Parameters
FFT Runtime Configuration and Status
Using the FFT Function with Array Interface
Using FFT Function with Streaming Interface
FIR Filter IP Library
FIR Static Parameters
Using the FIR Function with Array Interface
Optional FIR Runtime Configuration
Using FIR Function with Streaming Interface
DDS IP Library
DDS Static Parameters
DDS Struct Parameter Values
SRL IP Library
Mapping Directly into SRL Resources
Read from the Shifter
Read, Write, and Shift Data
Read, Write, and Enable-Shift
Vitis HLS Migration Guide
Migrating to Vitis HLS
Key Behavioral Differences
Default User Control Settings
Vivado IP Development Flow
Vitis Application Acceleration Development Flow (Kernel Mode)
Default Interfaces
Interface Bundle Rules
Memory Property on Interface
AXI4-Stream Interfaces with Side-Channels
Memory Model
Unconnected Ports
Global Variables on the Interface
Behavior Changes to Module Names and Module Prefix
Updated Memory (RAM/ROM) Module Name and RTL File Name
Behavior differences in Inlining of functions
Dataflow
Deprecated and Unsupported Features
Unsupported Features
Assertions
Pragmas
Top-Level Function Argument
HLS Video Library
C Arbitrary Precision Types
Additional Resources and Legal Notices
Finding Additional Documentation
Support Resources
References
Revision History
Please Read: Important Legal Notices

This section contains the following chapters:

Navigating Content by Design Process
Supported Operating Systems for Vitis HLS
Benefits of High-Level Synthesis
Introduction to Vitis HLS
Introduction to the new Vitis Unified IDE
Tutorials and Examples

Back to home page