HLS IP Gen Handbook - User documentation for the HLS IP Gen compiler - 2026-07-24

Version: current
Product Type
Resource Type
Source Name: Markdown

1 Altera® HLS IP Gen Handbook
2 Getting Started with the Altera® HLS IP Gen for Altera® FPGA Development
2.1 System Requirements
2.2 Installing the Altera® HLS IP Gen Tool
2.2.1 Installer Troubleshooting
2.2.1.1 "No user namespace available"
2.2.1.2 Simulation compile fault with "acl_pkg_pack: Unable to start modelsim.ini: No such file or directory"
2.2.1.3 Host packages
2.2.1.4 Installing additional libraries in the Apptainer environment
2.2.2 Installing Prerequisites Individually
2.2.3 Uninstalling the Altera® HLS IP Gen Tool
3 Introduction to FPGA Design Concepts
3.1 FPGA Architecture Overview
3.1.1 Register
3.1.2 Lookup Table (LUT)
3.1.3 Adaptive Logic Module (ALM)
3.1.4 Digital Signal Processing (DSP) Block
3.1.5 Random Access Memory (RAM) Blocks
3.2 Concepts of FPGA Hardware Design
3.2.1 Maximum Frequency (fMAX)
3.2.2 Latency
3.2.3 Pipelining
3.2.4 Throughput
3.2.5 Datapath
3.2.6 Control Path
3.2.7 Occupancy
3.3 How Source Code Becomes a Custom Hardware Datapath
3.3.1 Mapping Source Code Instructions to Hardware
3.3.1.1 Mapping Operations to Hardware
3.3.1.2 Mapping Arrays and Their Accesses to Hardware
3.3.2 Scheduling
3.3.2.1 Clustering the Datapath
3.3.3 Mapping Parallelism Models to FPGA Hardware
3.3.3.1 Data Parallelism
3.3.3.2 Executing Independent Operations Simultaneously
3.3.3.3 Parallel Execution Through Pipelining
3.3.3.4 Task Parallelism
3.3.4 Memory Types
3.3.4.1 Kernel Memory
3.3.4.2 Global Memory
4 Altera® HLS IP Gen FPGA Development
4.1 FPGA Flow Terminology
4.2 Altera® HLS IP Gen FPGA Development Flow
4.3 Types of SYCL* FPGA Compilation
4.3.1 Separating Device and Host Code Compilation
4.3.1.1 Using the -reuse-exe Flag
4.3.1.2 Using the Device Link Method
4.3.1.3 Which Mechanism to Use?
4.4 FPGA Compilation Flags
4.4.1 Common Commands and Flags
4.4.2 Other SYCL* FPGA Flags Supported by the Compiler
5 Defining a Kernel for FPGAs
5.1 Suggested Kernel Coding Styles
5.2 Kernel Design Guidelines
5.2.1 Single-Task Kernel Design Guidelines
5.2.2 Single-Cycle Floating-Point Accumulator
5.2.2.1 Strategies for Inferring the Accumulator
5.3 Device Selectors for FPGA
6 Emulate Your Design
6.1 Compile and Emulate Your Design
6.2 Emulator Environment Variables
6.2.1 Emulate Pipe Depth
6.3 Debugging with printf Command in Emulation
6.4 Emulator Limitations
6.5 Emulator Known Issues
6.6 Troubleshooting Discrepancies in Hardware and Emulator Results
7 Simulate Your Design
7.1 Compile and Simulate Your Design
7.1.1 Compiling for Simulation
7.1.2 Running Simulation
7.2 Viewing Simulation Waveforms
7.3 Troubleshooting Simulator Issues
8 Analyzing Your Design
8.1 Review the FPGA Optimization Report
8.1.1 Loop Analysis
8.1.2 Bottlenecks Viewer
8.1.3 Area Estimates
8.1.4 System Viewer
8.1.5 Kernel Memory Viewer
8.1.6 Schedule Viewer
8.1.7 Access FPGA Optimization Reports in JSON Format
8.2 Simulation Dynamic Statistics Viewer
8.3 Quartus® (Static) Summary
8.3.1 Timing Failures
9 Integrate Your Design
9.1 Integrating Your RTL IP Core Into a System
9.1.1 Synthesize Your RTL IP Core with Quartus® Prime Software
9.1.2 Add an RTL IP Core into a Platform Designer System
9.1.3 Add an RTL IP Core into a Quartus® Prime Project
9.2 Integrating Your Kernel into DSP Builder for Altera® FPGAs
10 RTL IP Core Interfaces
10.1 IP Interface Summary
10.1.1 Interface Types and Protocols
10.1.2 Interface Functionalities
10.1.3 Functionality vs. Interface Type Matrix
10.2 Kernel Interfaces
10.2.1 Kernel Invocation Interfaces
10.2.1.1 Register-Mapped Invocation Interface
10.2.1.1.1 Using Register-Mapped Invocation Interface
10.2.1.1.2 Register Map Layout
10.2.1.2 Streaming Invocation Interface
10.2.1.2.1 Using Streaming Invocation Interface
10.2.1.2.2 Limitations of Streaming Kernels
10.2.2 Kernel Argument Interfaces
10.2.2.1 struct as Kernel Argument
10.3 Non-Kernel Interfaces
10.3.1 Memory-Mapped Host Interfaces
10.3.1.1 Memory-Mapped Host Interfaces with Unified Shared Memory Pointers
10.3.1.1.1 The annotated_arg Template Class
10.3.1.1.2 Using Annotated USM Pointer Arguments
10.3.1.1.3 Mixing Annotated and Unannotated Pointer Arguments
10.3.1.2 Memory-Mapped Host Interfaces with Accessors
10.3.1.2.1 Accessor Properties
10.3.1.2.2 Using Annotated Accessors
10.4 Reset Interface
10.4.1 Reset Behavior
11 Pipes
11.1 Pipe Types and Classification
11.1.1 Inter-Kernel Pipes
11.1.2 Streaming Host Pipes
11.1.3 CSR Host Pipes
11.1.4 Pipe Types Comparison
11.2 Using Pipes
11.2.1 Pipe Templated Class
11.2.1.1 Pipe Properties Class
11.2.2 Declaring Pipes
11.2.3 Pipe API
11.3 Pipes and Atomic Fence
11.4 Host Pipe RTL Interfaces
11.4.1 Streaming Protocols
11.4.1.1 Non-Zero Ready Latency
11.4.1.2 Stall-Free Streaming
11.4.1.3 Streaming Sideband Signals
11.4.2 Memory-Mapped Protocol
12 Loops
12.1 Refactor the Loop-Carried Data Dependency
12.2 Relax Loop-Carried Dependency
12.3 Transfer Loop-Carried Dependency to Local Memory
12.4 Minimize the Memory Dependencies for Loop Pipelining
12.5 Unroll Loops
12.6 Fuse Loops to Reduce Overhead and Improve Performance
12.7 Optimize Loops With Loop Speculation
12.8 Remove Loop Bottlenecks
12.9 Improve fMAX/II with Shannonization
12.10 Optimize Inner Loop Throughput
12.11 Improve Loop Performance by Caching Data in On-Chip Memory
13 Parallelism
13.1 Pipelined Kernels
13.1.1 The pipelined Kernel Property
13.1.2 Stable Arguments
13.2 Asynchronous Parallelism Within Kernels (task_sequence)
13.2.1 The task_sequence Template Class
13.2.1.1 task_sequence Properties
13.2.1.2 task_sequence Function API
13.2.2 Using task_sequence
13.2.3 Task Functions
13.2.3.1 Task Invocation Interface
13.2.3.2 Scope, Lifetime, and Reuse of task_sequence Objects
13.2.4 task_sequence Use Cases
14 Data Types and Arithmetic Operations
14.1 Optimize Floating-point Operation
14.2 Minimize the Use of Expensive Functions
14.3 Variable-Precision Data Type Support
14.3.1 Advantages and Limitations of Variable Precision Data Types
14.3.2 Declare and Use the AC Data Types
14.3.2.1 Declare the ac_int Data Type
14.3.2.2 Declare the ac_fixed Data Type
14.3.2.3 Declare the ac_complex Data Type
14.3.2.4 Declare the ap_float Data Type
14.3.2.4.1 Conversion Rules for the ap_float Data Type
14.3.2.4.2 Operations with Explicit Precision Controls
14.3.2.4.3 Comparison Operators
14.3.2.4.4 Additional ap_float Functions
14.3.2.4.5 Additional Data Types Provided by the ap_float.hpp Header File
14.3.2.4.6 Quality of Results and the ap_float Data Type
15 Memories and Memory Operations
15.1 Memory Types
15.1.1 On-Chip Memory
15.1.2 Global Memory
15.1.2.1 Global Memory Bandwidth Calculation
15.2 Load-Store Units
15.2.1 Load-Store Unit Styles
15.2.1.1 Burst-Coalesced Load-Store Units
15.2.1.2 Prefetching Load-Store Units
15.2.1.3 Pipelined Load-Store Units
15.2.1.4 Load-Store Unit Comparison
15.2.2 Load-Store Unit Controls
15.3 Unified Shared Memory
15.3.3 Annotating USM Pointers with Buffer Location
15.4 Persistent Memory Storage (device_global)
15.4.1 device_global Templated Class
15.4.2 device_global Declaration and Initialization
15.4.3 Accessing device_global
15.4.4 device_global Hardware Implementation
15.5 Memory Optimizations
15.5.1 Local and Private Memory Accesses Optimization
15.5.1.1 General Guidelines
15.5.1.2 Local Memory Banks
15.5.1.3 Perform Kernel Computations Using Local or Private Memory
15.5.1.4 Inferring a Shift Register
15.5.2 Global Memory Accesses Optimization
15.5.2.1 Ignoring Dependencies Between Pointer-Type Arguments
15.5.2.2 Annotating USM Pointers
15.5.2.3 Dynamic Burst Coalescing
15.5.3 Other Optimization Techniques
15.5.3.1 Static Memory Coalescing
15.5.3.2 Additional Memory Optimization Recommendations
15.5.4 Memory Optimization Summary
16 FPGA Optimization Flags, Attributes, Pragmas, and Extensions
16.1 Optimization Flags
16.1.1 Specify Schedule fMAX Target for Kernels (-Xsclock=<clock target>)
16.1.2 Create a 2xclock Interface (-Xsuse-2xclock)
16.1.3 Force Ring Interconnect for Global Memory (-Xsglobal-ring)
16.1.4 Force a Single Store Ring to Reduce Area (-Xsforce-single-store-ring)
16.1.5 Force Fewer Read Data Reorder Units to Reduce Area (-Xsnum-reorder)
16.1.6 Disable Hardware Kernel Invocation Queue (-Xsno-hardware-kernel-invocation-queue)
16.1.7 Improve fMAX on HyperFlex® Fabrics
16.1.8 Disable Automatic Fusion of Loops (-Xsdisable-auto-loop-fusion)
16.1.9 Fuse Adjacent Loops With Unequal Trip Counts (-Xsenable-unequal-tc-fusion)
16.1.10 Pipeline Loops in Non-task Kernels (-Xsauto-pipeline)
16.1.11 Control Semantics of Floating-Point Operations (-ffp-model=<value>)
16.1.12 Modify the Rounding Mode of Floating-point Operations (-Xsrounding=<rounding_type>)
16.1.13 Global Control of Exit FIFO Latency of Stall-free Clusters (-Xssfc-exit-fifo-type=<value>)
16.1.14 Enable the Read-Only Cache for Read-Only Accessors (-Xsread-only-cache-size=<N>)
16.1.15 Control Hardware Implementation of the Supported Data Types and Math Operations (-Xsdsp-mode=<option>)
16.1.16 Generate Register Map Wrapper (-Xsregister-map-wrapper-type)
16.1.17 Allow Wide Memory Initialization (-Xsallow-wide-device-globals)
16.2 Optimization Targets
16.2.1 Minimum Latency Flow
16.2.2 Minimum Area Flow
16.2.3 Balanced Throughput-Area Trade-Offs Flow
16.3 Kernel Variables
16.4 Kernel Attributes
16.4.1 Specify Schedule fMAX Target for Kernels (scheduler_target_fmax_mhz)
16.4.2 Specify a Work-Group Size (max_work_group_size/reqd_work_group_size)
16.4.3 Specify Number of SIMD Work Items (num_simd_work_items)
16.4.4 Omit Hardware that Generates and Dispatches Kernel IDs (max_global_work_dim)
16.4.5 Reduce Kernel Area and Latency (use_stall_enable_clusters)
16.5 FPGA Memory Attributes
16.6 Loop Directives
16.6.1 disable_loop_pipelining Attribute
16.6.2 initiation_interval Attribute
16.6.3 ivdep Attribute
16.6.4 loop_coalesce Attribute
16.6.5 max_concurrency Attribute
16.6.6 max_interleaving Attribute
16.6.7 speculated_iterations Attribute
16.6.8 unroll Pragma
16.6.9 Loop Fuse Functions and nofusion Attribute
16.6.10 max_reinvocation_delay Attribute (Beta)
16.7 Floating-Point Pragmas
16.8 Latency Controls (Beta)
17 Libraries
17.1 Use of RTL Libraries for FPGA
17.2 Creating an RTL Library
17.2.1 Create Library Objects From Source Code
17.2.2 Package Object Files into a Library File
17.2.3 Using Libraries
17.3 Manifest File Syntax of an RTL Library
17.4 Restrictions and Limitations in RTL Support
17.5 Agilex™ 7 and Stratix® 10 Design-Specific Reset Requirements for Stall-Free and Stallable RTL Libraries
17.6 Stall-Free RTL
18 Quick Reference
18.1 Algorithmic C Data Types
18.1.1 Compilation Flags
18.1.2 Explicit Conversion Functions
18.1.3 Math Functions Provided by the ac_fixed_math.hpp Header File
18.1.4 Math Functions Provided by ap_float_math.hpp Header File
18.2 Floating Point Pragmas
18.3 FPGA Accessor Properties
18.4 USM Pointer Properties
18.4.1 MM Host Interface Properties
18.5 FPGA Extensions
18.5.1 The device_global Extension
18.5.2 The fpga_datapath Extension
18.5.3 The fpga_reg Extension
18.5.4 The task_sequence Extension
18.6 FPGA Kernel Attributes
18.7 Kernel Interfaces
18.7.1 Kernel Invocation Interface Properties
18.7.2 Kernel Argument Interface Properties
18.7.3 Pipelined Kernel Property
18.8 Latency Control Properties (Beta)
18.8.1 latency_control_type Values
18.9 FPGA LSU Controls
18.10 FPGA Loop Directives
18.11 Memory Attributes
18.11.1 Struct Data Types and Memory Attributes
18.12 FPGA Optimization Flags
18.13 Pipe API
18.13.1 Pipe Properties
19 Additional Information
20 Document Revision History for the Altera® HLS IP Gen Handbook for Altera® FPGAs
21 Notices and Disclaimers

Back to home page