Defining Interfaces - 2025.2 English - UG1399

Vitis High-Level Synthesis User Guide (UG1399)

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

Introduction
Navigating Content by Design Process
Supported Operating Systems for Vitis HLS
Obtaining a Vitis HLS License
Changed Behavior
Benefits of High-Level Synthesis
Introduction to Vitis HLS Components
Refactoring C++ Source Code for HLS
Tutorials and Examples
HLS Programmers Guide
Design Principles
Three Paradigms for Programmable Logic
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
Dataflow Region Coding Style
WYSIWYG Coding Style
Nested Dataflow Region Pitfalls
Advanced Dataflow Region Examples
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
Arbitrary Precision Floating-Point Library ap_float<int W, int E>
Dealing with Unsupported Functions
Conversions of ap_float<> To and From Other Data Types
Accumulation of ap_float<> Using ap_float_acc<> Helper Class
Using ap_float_acc<> Restrictions
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
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
Customizing AXI4-Stream Interfaces
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
Improving HBM Bandwidth with Multiple M_AXI Interfaces
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
Continuously Running Mode
Auto-Restarting Mode
Working with Auto-Restarting Designs
Supported Interfaces
Enabling Auto-Restart
Using the Mailbox
Mailbox Semantics
Using Auto-Restart in Cosimulation (C/RTL Cosim)
Programmer’s Model
Auto-Restart Limitations
Using Auto-Restart in XRT
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
Top-Level Performance Pragma
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
Stencil Optimizations
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
DSP Multi-Operation Matching
Controlling Operator Pipelining
Unrolling Loops in C++ Classes
Limitations of Control-Driven Task-Level Parallelism
Limitations of Pipelining with Static Variables
Vitis HLS Flow Steps
Launching the Vitis Unified IDE
Features of the Vitis Unified IDE
Using the Flow Navigator
Building and Running an HLS Component
Creating an HLS Component
Target Flow Overview
Default Settings of Vivado/Vitis Flows
Working with Sources
Coding C/C++ Functions
Using Libraries in HLS Components
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
Defining the HLS Config File
Specifying the Clock Frequency
Clock and Reset Ports
Adding Pragmas and Directives
Conditional Control of Pragmas
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
Running C Simulation
Writing a Test Bench
Example Test Bench
Design Files and Test Bench Files
Single File Test Bench and Design
Sanitizers During C Simulation
Output of C Simulation
Using Code Analyzer
Debugging the HLS Component
Running C Synthesis
Improving Synthesis Runtime and Capacity
Output of C Synthesis
Synthesis Summary
Function Call Graph
Schedule Viewer
Dataflow Viewer
Running C/RTL Co-Simulation
Output of C/RTL Co-Simulation
Automatically Verifying the RTL
Co-simulation Requirements for Interface Synthesis
Verification of DATAFLOW and DEPENDENCE
Unsupported Optimizations for Co-Simulation
Simulating IP Cores
Analyzing RTL Simulations
Viewing Simulation Waveforms
Cosim Deadlock Detection
Timeline Trace Viewer
Troubleshooting C/RTL Co-Simulation
Setting Up the Environment
Optimization Directives
C Test Bench and C Source Code
Packaging the RTL Design
Output of RTL Export
Running Implementation
Implementation Report
Optimizing the HLS Project
Cloning HLS Components
Component Comparison Feature
L1 Library Wizard Flow
Creating HLS Components from the Command Line
Vitis HLS Command Reference
vitis, v++, and vitis-run Commands
hls_init.tcl
HLS Config File Commands
HLS General Options
Array Partition 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.cache
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
pragma HLS aggregate
pragma HLS alias
pragma HLS allocation
pragma HLS array_partition
pragma HLS array_reshape
pragma HLS array_stencil
pragma HLS bind_op
pragma HLS bind_storage
pragma HLS cache
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
HLS Tcl Commands
Project Commands
add_files
apply_ini
cat_ini
close_project
close_solution
cosim_design
cosim_stall
create_clock
create_derived_clock
csim_design
csynth_design
delete_project
delete_solution
enable_beta_device
export_design
get_clock_period
get_clock_uncertainty
get_component
get_derived_clock
get_files
get_part
get_project
get_solution
get_top
help
list_part
open_component
open_project
open_solution
open_tcl_project
project2ini
set_clock_uncertainty
set_part
set_top
write_component
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_sim
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_cache
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
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
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
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 Direct I/O
Using Direct I/O Streams
Mapping Direct I/O Streams to a Wire Interface
Mapping Direct I/O Streams to SAXI Lite Interface
Blocking/Non-Blocking API
HLS Fence Library
HLS Vector Library
HLS Task Library
Support of Scalars/Memory Interfaces in DTLP
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
DSP Intrinsics
Using DSP Intrinsics
Unsigned Inputs
Accumulation
DSP Cascading
DSP Complex Intrinsics
Fast Fourier Transform IP Library
FIR Filter IP Library
FIR Static Parameters
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
Working with OpenCV
Vitis HLS Migration Guide
Migrating from Vitis HLS to the Vitis Unified IDE
Migrating from Vivado HLS 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
Pragmas
Top-Level Function Argument
HLS Video Library
C Arbitrary Precision Types
Tcl to Config File Command Map
Instruction/Operator Explanation
Additional Resources and Legal Notices
Finding Additional Documentation
Support Resources
References
Revision History
Please Read: Important Legal Notices

Back to home page