Arrays Primer - Arrays Primer - 2026.1 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID: UG1399
Release Date: 2026-06-23
Version: 2026.1 English

Introduction
Navigating Content by Design Process
Operating Systems and C++ Support
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 Cosimulation 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
Canonical Dataflow
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
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 and Directives
Aggregate
Alias
Allocation
Array_partition
Array_reshape
Array_stencil
Bind_op
Bind_storage
Cache
Dataflow
Dependence
Disaggregate
Expression_balance
Function_instantiate
Inline
Interface
Latency
Loop_flatten
Loop_merge
Loop_tripcount
Occurrence
Performance
Pipeline
Protocol
Reset
Stable
Stream
Top
Unroll
HLS Tcl Commands
Project Commands
Configuration Commands
HLS General Options
C-Synthesis Sources
Test Bench Sources
Array Partition
Array Stencil
Compile
C Simulation
Co-simulation
Dataflow
Debug
Interface
Package/Export
Op Binding
RTL
Schedule
Storage Binding
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