Developer Guide

Intel® oneAPI DPC++/C++ Compiler Handbook for FPGAs

Download PDF
ID 785441
Date 6/24/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
Intel oneAPI DPC++/C++ Compiler Handbook for FPGAs Overview Introduction To FPGA Design Concepts Intel oneAPI FPGA Development Getting Started with the Intel oneAPI DPC++/C++ Compiler for Intel FPGA Development Defining a Kernel for FPGAs Debugging and Verifying Your Design Analyzing Your Design Optimizing Your Kernel Optimizing Your Host Application Integrating Your Kernel into DSP Builder for Intel FPGAs Integrating Your RTL IP Core Into a System RTL IP Core Kernel Interfaces Loops Pipes Data Types and Arithmetic Operations Parallelism Memories and Memory Operations Libraries Additional FPGA Acceleration Flow Considerations FPGA Optimization Flags, Attributes, Pragmas, and Extensions Quick Reference Additional Information Document Revision History for the Intel oneAPI DPC++/C++ Compiler Handbook for Intel FPGAs Notices and Disclaimers
Introduction To FPGA Design Concepts x
FPGA Architecture Overview Concepts of FPGA Hardware Design How Source Code Becomes a Custom Hardware Datapath
How Source Code Becomes a Custom Hardware Datapath x
Mapping Source Code Instructions to Hardware Scheduling Mapping Parallelism Models to FPGA Hardware Memory Types
Intel oneAPI FPGA Development x
FPGA Flow Terminology Intel oneAPI FPGA Development Flow Types of SYCL* FPGA Compilation FPGA Compilation Flags FPGA Workflows in IDEs
Types of SYCL* FPGA Compilation x
Separating Device and Host Code Compilation
Getting Started with the Intel oneAPI DPC++/C++ Compiler for Intel FPGA Development x
Installing the Intel oneAPI FPGA Development Environment FPGA Development for Intel oneAPI Toolkits with Visual Studio* Code
Installing the Intel oneAPI FPGA Development Environment x
Simulation Prerequisites Installing the Questa*-Intel FPGA Edition Software Set Up the Simulation Environment
FPGA Development for Intel oneAPI Toolkits with Visual Studio* Code x
Set the Environment Variables and Launch Visual Studio* Code Create an FPGA Visual Studio* Code Project Enable Code Completion in a Visual Studio* Code Project Configure Running and Debugging in a Visual Studio* Code Project Debugging Your Kernel in Visual Studio* Code with a Native Debugger Generate and View the FPGA Optimization Report Build and Run the FPGA Hardware Image
Defining a Kernel for FPGAs x
Suggested Kernel Coding Styles Single Work-Item Kernels
Single Work-Item Kernels x
Single Work-item Kernel Design Guidelines Single-Cycle Floating-Point Accumulator for Single Work-Item Kernels
Single-Cycle Floating-Point Accumulator for Single Work-Item Kernels x
Strategies for Inferring the Accumulator
Debugging and Verifying Your Design x
Device Selectors for FPGA printf Command Restrictions Emulate and Debug Your Design Evaluate Your Kernel Through Simulation
Emulate and Debug Your Design x
Emulator Environment Variables Compile and Emulate Your Design Limitations of the Emulator Troubleshooting Discrepancies in Hardware and Emulator Results Emulator Known Issues
Evaluate Your Kernel Through Simulation x
Debug During Verification Compile a Kernel for Simulation Simulate Your Kernel Viewing Simulation Waveforms Troubleshooting Simulator Issues
Analyzing Your Design x
Review the FPGA Optimization Report Quartus (Static) Summary Intel® FPGA Dynamic Profiler for DPC++
Review the FPGA Optimization Report x
Loop Analysis Bottlenecks Viewer Area Estimates System Viewer Kernel Memory Viewer Schedule Viewer Access FPGA Optimization Reports in JSON Format
Quartus (Static) Summary x
Timing Failures
Intel® FPGA Dynamic Profiler for DPC++ x
Measure Kernel Performance Instrument the Kernel Pipeline with Performance Counters (-Xsprofile) Obtain Profiling Data During Run Time Reduce Area Resource Use While Profiling Profiler Analyses of Example SYCL* Design Scenarios Limitations
Obtain Profiling Data During Run Time x
Invoke the Profiler Runtime Wrapper to Obtain Profiling Data Use Intel® VTune™ Profiler
Use Intel® VTune™ Profiler x
Interpret Performance Counter Data
Optimizing Your Host Application x
Throughput Resource Use System-level Profiling Using the Intercept Layer for OpenCL™ Applications Multithreaded Host Application Utilizing Hardware Kernel Invocation Queue Double Buffering Host Utilizing Kernel Invocation Queue N-Way Buffering to Overlap Kernel Execution Prepinning Memory Simple Host-Device Streaming Buffered Host-Device Streaming
System-level Profiling Using the Intercept Layer for OpenCL™ Applications x
Set Up the Intercept Layer for OpenCL™ Applications
Double Buffering Host Utilizing Kernel Invocation Queue x
Analyzing Buffering Using the Intercept Layer for OpenCL™ Applications
Integrating Your RTL IP Core Into a System x
Synthesize Your RTL IP Core with Quartus Prime Software Encrypting RTL IP Cores Add an RTL IP Core into a Platform Designer System Add an RTL IP Core into a Quartus Prime Project
Encrypting RTL IP Cores x
Encrypting RTL IP Cores Without Licensing Encrypting RTL IP Core With Licensing
RTL IP Core Kernel Interfaces x
Kernel Argument Interfaces Memory-Mapped (MM) Agent Kernel Invocation Interface Ready/Valid Handshaking Kernel Invocation Interface Memory-Mapped Host Interfaces Structs in RTL IP Core Interfaces IP core Reset Behavior
Memory-Mapped Host Interfaces x
Memory-Mapped Host Interfaces Using Unified Shared Memory Pointers and the annotated_arg Class Memory-Mapped Host Interfaces Using Accessors
Memory-Mapped Host Interfaces Using Unified Shared Memory Pointers and the annotated_arg Class x
Buffer Locations in Memory-Mapped Host Interfaces The annotated_arg Template Class
Loops x
Refactor the Loop-Carried Data Dependency Relax Loop-Carried Dependency Transfer Loop-Carried Dependency to Local Memory Minimize the Memory Dependencies for Loop Pipelining Unroll Loops Fuse Loops to Reduce Overhead and Improve Performance Optimize Loops With Loop Speculation Remove Loop Bottlenecks Improve fMAX/II with Shannonization Optimize Inner Loop Throughput Improve Loop Performance by Caching Data in On-Chip Memory
Pipes x
Host Pipes Pipes Extension
Host Pipes x
Host Pipe Declaration Host Pipe API Host Pipes RTL Interfaces
Pipes Extension x
Key Properties of a Pipe Accessing Pipes The pipe Class and its Use I/O Pipes Characteristics of Pipes Restrictions of Pipes Guidelines for Designing Pipes The atomic_fence Function and Pipes
I/O Pipes x
Emulate Applications with a Pipe That Reads or Writes to an I/O Pipe
Data Types and Arithmetic Operations x
Optimize Floating-point Operation Minimize the Use of Expensive Functions Variable-Precision Data Type Support
Variable-Precision Data Type Support x
Advantages and Limitations of Variable Precision Data Types Declare and Use the AC Data Types
Declare and Use the AC Data Types x
Declare the ac_int Data Type Declare the ac_fixed Data Type Declare the ac_complex Data Type Declare the ap_float Data Type
Declare the ap_float Data Type x
Conversion Rules for the ap_float Data Type Operations with Explicit Precision Controls Comparison Operators Additional ap_float Functions Additional Data Types Provided by the ap_float.hpp Header File Quality of Results and the ap_float Data Type
Parallelism x
Pipelined Kernels NDRange Kernels Asynchronous Parallelism Within Kernels (task_sequence)
Pipelined Kernels x
Stable Arguments
Asynchronous Parallelism Within Kernels (task_sequence) x
Task Functions task_sequence Use Cases
Memories and Memory Operations x
The device_global Extension (Beta) The annotated_ptr Template Class (Beta) Memory Accesses Kernel Variable Accesses
Memory Accesses x
Load-Store Units Global Memory Accesses Optimization Perform Kernel Computations Using Local or Private Memory Local and Private Memory Accesses Optimization Annotating Unified Shared Memory Pointers Zero-Copy Memory Access Additional Recommendations
Load-Store Units x
Load-Store Unit Styles Load-Store Unit Modifiers Load-Store Unit Controls
Global Memory Accesses Optimization x
Global Memory Bandwidth Use Calculation Manual Partition of Global Memory Partitioning Buffers Across Different Memory Types (Heterogeneous Memory) Partitioning Buffers Across Memory Channels of the Same Memory Type Ignoring Dependencies Between Accessor Arguments Contiguous Memory Accesses Static Memory Coalescing
Libraries x
Use SYCL Shared Library With Third-Party Applications Use of RTL Libraries for FPGA Object Manifest File Syntax of an RTL Library Restrictions and Limitations in RTL Support Agilex 7 and Stratix 10 Design-Specific Reset Requirements for Stall-Free and Stallable RTL Libraries Stall-Free RTL
Additional FPGA Acceleration Flow Considerations x
FPGA-CPU Interaction FPGA Boards and Board Support Packages (BSPs) Targeting Multiple Identical FPGA Devices Targeting Multiple Platforms Split Kernel into Multiple FPGA Images (Linux only)
FPGA Boards and Board Support Packages (BSPs) x
The FPGA Board Utility Commands Managing an FPGA Board Advanced Board Management The OpenCL™ Installable Client Driver (ICD)
Advanced Board Management x
Extracting the FPGA Device Image (.aocx) File from a Multiarchitecture Binary File
FPGA Optimization Flags, Attributes, Pragmas, and Extensions x
Optimization Flags Optimization Targets Kernel Variables Kernel Attributes Memory Attributes Loop Directives Floating-Point Pragmas Latency Controls (Beta)
Optimization Flags x
Specify Schedule fMAX Target for Kernels (-Xsclock=<clock target>) Create a 2xclock Interface (-Xsuse-2xclock) Disable Burst-Interleaving of Global Memory (-Xsno-interleaving) Force Ring Interconnect for Global Memory (-Xsglobal-ring) Force a Single Store Ring to Reduce Area (-Xsforce-single-store-ring) Force Fewer Read Data Reorder Units to Reduce Area (-Xsnum-reorder) Disable Hardware Kernel Invocation Queue (-Xsno-hardware-kernel-invocation-queue) Modify the Handshaking Protocol Between Clusters (-Xshyper-optimized-handshaking) Disable Automatic Fusion of Loops (-Xsdisable-auto-loop-fusion) Fuse Adjacent Loops With Unequal Trip Counts (-Xsenable-unequal-tc-fusion) Pipeline Loops in Non-task Kernels (-Xsauto-pipeline) Control Semantics of Floating-Point Operations (-fp-model=<value>) Modify the Rounding Mode of Floating-point Operations (-Xsrounding=<rounding_type>) Global Control of Exit FIFO Latency of Stall-free Clusters (-Xssfc-exit-fifo-type=<value>) Enable the Read-Only Cache for Read-Only Accessors (-Xsread-only-cache-size=<N>) Control Hardware Implementation of the Supported Data Types and Math Operations (-Xsdsp-mode=<option>) Generate Register Map Wrapper (-Xsregister-map-wrapper-type) Allow Wide Memory Initialization (-Xsallow-wide-device-globals)
Optimization Targets x
Minimum Latency Flow Minimum Area Flow Balanced Throughput-Area Trade-Offs Flow
Kernel Attributes x
Specify Schedule fMAX Target for Kernels (scheduler_target_fmax_mhz) Specify a Workgroup Size (max_work_group_size/reqd_work_group_size) Specify Number of SIMD Work Items (num_simd_work_items) Omit Hardware that Generates and Dispatches Kernel IDs (max_global_work_dim) Omit Hardware that Supports Global Work Offsets (no_global_work_offset) Reduce Kernel Area and Latency (use_stall_enable_clusters)
Loop Directives x
disable_loop_pipelining Attribute initiation_interval Attribute ivdep Attribute loop_coalesce Attribute max_concurrency Attribute max_interleaving Attribute speculated_iterations Attribute unroll Pragma Loop Fuse Functions and nofusion Attribute max_reinvocation_delay Attribute (Beta)
Quick Reference x
Algorithmic C Data Types Floating Point Pragmas FPGA Accessor Properties FPGA Extensions FPGA Kernel Attributes FPGA Local Memory Function Latency Control Properties (Beta) FPGA LSU Controls FPGA Loop Directives FPGA Memory Attributes FPGA Optimization Flags Pipe API
Intel oneAPI DPC++/C++ Compiler Handbook for FPGAs Overview
Introduction To FPGA Design Concepts
Intel oneAPI FPGA Development
Getting Started with the Intel oneAPI DPC++/C++ Compiler for Intel FPGA Development
Defining a Kernel for FPGAs
Debugging and Verifying Your Design
Analyzing Your Design
Optimizing Your Kernel
Optimizing Your Host Application
Integrating Your Kernel into DSP Builder for Intel FPGAs
Integrating Your RTL IP Core Into a System
RTL IP Core Kernel Interfaces
Loops
Pipes
Data Types and Arithmetic Operations
Parallelism
Memories and Memory Operations
Libraries
Additional FPGA Acceleration Flow Considerations
FPGA Optimization Flags, Attributes, Pragmas, and Extensions
Quick Reference
Additional Information
Document Revision History for the Intel oneAPI DPC++/C++ Compiler Handbook for Intel FPGAs
Notices and Disclaimers

Document Revision History for the Intel oneAPI DPC++/C++ Compiler Handbook for Intel FPGAs

Date Release Version Changes
June 2024 2024.2
  • Revised code examples in Optimize Inner Loop Throughput
  • Added "Filtering Nodes in Report Tables" to Review the FPGA Optimization Report
  • Revised Reduce Kernel Area and Latency (use_stall_enable_clusters).
  • Revised Declare the ap_float Data Type.
  • Revised Host Pipes RTL Interfaces.
  • Revised Partitioning Buffers Across Memory Channels of the Same Memory Type.
  • Added the no_offset property to FPGA Accessor Properties.
  • Revised The pipe Class and its Use.
  • Revised latency property description in The annotated_arg Template Class and Memory-Mapped Host Interfaces Using Unified Shared Memory Pointers and the annotated_arg Class
  • Revised fpga_register description in Memory Attributes
  • Added Structs in RTL IP Core Interfaces
  • Revised Pipelined Kernels.
  • Revised ivdep Attribute.
  • Removed references to the --target sycl and --source sycl options of the fpga_crossgen and fpga_libtool commands. There options are no longer required and have been removed from the commands.
  • Replaced occurrences of <project_name>_di_inst.v with <project_name>_di_inst.sv.
  • Added Allow Wide Memory Initialization (-Xsallow-wide-device-globals).
  • Revised references to icpx -fscyl -fintelfpga commands to icpx -fintelfpga. The -fintelfpga option includes the -fsycl option, so specifying the -fsycl option is redunant.
  • Added Managing an FPGA Board.
  • Added Linking Your Host Application to the Khronos ICD Loader Library.
May 2024 2024.1
  • Fix broken links
March 2024 2024.1
  • Changed the title of this document to Intel® oneAPI DPC++/C++ Compiler Handbook for Intel FPGAs.
  • Added The annotated_ptr Template Class.
  • Added Getting Started with Intel® oneAPI FPGA Development chapter. This chapter includes the following sections:
    • Installing the Intel® oneAPI FPGA Development Environment
    • FPGA Development for Intel® oneAPI Toolkits with Visual Studio* Code

      This section includes content that was previously provided in FPGA Development for Intel® oneAPI Toolkits with Visual Studio Code on Linux*.

      This section also includes new topics Enable Code Completion in Visual Studio Code and Debugging You Kernel In Visual Studio Code.

  • Revised Minimum Latency Flow.
  • Revised Balanced Throughput-Area Trade-Offs Flow.
  • Added Minimum Area Flow.
  • Revised information about encrypting your RTL IP core. Refer to Encrypting RTL IP Core for details.
  • Added Allow Wide Memory Initialization (-Xsallow-wide-mif) optimization target.
  • Added Integrating Your Kernel into DSP Builder for Intel FPGAs.
  • Removed references the following macros:
    • mmhost
    • register_map_mmhost
    • conduit_mmhost
    • streaming_interface
    • streaming_pipelined_interface
  • Deprecated the --emulation_model option of the fpga_crossgen. Use the --cpp_model option instead.
  • Renamed register_map_offsets.hpp and <kernel_name>_register_map.hpp files. Starting with oneAPI 2024.1, these files are register_map_offsets.h and <kernel_name>_register_map.h, respectively.
  • Revised FPGA BSPs and Boards.
  • Revised FPGA Compilation Flags
  • Changed the default compilation target when you do not specify the -Xstarget compiler option. If you do not specify the option, the compiler assumes -Xstarget=Agilex7. Previously, the default target was -Xstarget=intel_a10gx_pac:pac_a10.
  • Revised The device_global Extension (Beta).
  • Revised Declare the ac_fixed Data Type.
  • Moved System-level Profiling Using the Intercept Layer for OpenCL™ Applications to Optimizing Your Host Application section.
  • Rebrand Intel Agilex® 7 as Agilex™ 7
  • Rebrand Intel® Arria® 10 as Arria® 10
  • Rebrand Intel® Cyclone® 10 GX as Cyclone® 10 GX
  • Rebrand Intel® Cyclone® V as Cyclone® V
  • Rebrand Intel® Stratix® 10 as Stratix® 10
  • Rebrand Intel® Quartus® Prime as Quartus® Prime

Document Revision History for the Intel® oneAPI FPGA Handbook

This document was previous title Intel® oneAPI FPGA Handbook.

Date Release Version Changes
January 2024 2024.0
  • Revised Memory-Mapped (MM) Agent Kernel Invocation Interface.

    The topic previous listed bit 0 of the Start register as "reserved". Bit 0 is now correctly labeled "start".
November 2023 2024.0
  • Created Intel® oneAPI FPGA Handbook with content from FPGA Optimization Guide for Intel® oneAPI Toolkits and Intel® oneAPI Programming Guide.
  • Deprecated the following macros:
    • mmhost
    • register_map_mmhost
    • conduit_mmhost
    • streaming_interface
    • streaming_pipelined_interface
    These macros will be removed in a future release.
  • Updated Conversion Rules for the ap_float Data Type.
  • Added Extracting the FPGA Hardware Configuration (.aocx) File from a Multiarchitecture Binary File.
  • Updated Agent IP Component Kernels.
  • Revised Host Pipes RTL Interfaces to indicate the restriction on simulation for host pipes with protocol_name::avalon_mm is lifted.
  • Updated The device_global Extension (Beta)
  • Revised Strategies for Inferring the Accumulator.
  • Renamed Maximum Throughput Without Area Optimization Heuristics Flow to Balanced Throughput-Area Trade-Offs Flow and revised the topic.
  • Revised ivdep Attribute
  • Added information about the annotated_arg class as follows:
    • Added Memory-Mapped Host Interfaces Using the annotated_arg Class
    • Added Avalon® Memory-Mapped Host Interfaces
    • Revised Memory-Mapped Host Interfaces
    • Revised Memory-Mapped Host Interfaces Using Unified Shared Memory
    • Revised Memory-Mapped Host Interfaces Using Accessors
  • Deprecated the [[intel::max_global_work_dim(0)]] kernel attribute in the following topics:
    • Omit Hardware that Generates and Dispatches Kernel IDs
    • FPGA Kernel Attributes
  • Renamed Agent IP Component Kernels to Avalon® Memory-Mapped (MM) Agent Kernel Invocation Interface and revised the topic.
  • Renamed Streaming IP Component Kernels to Ready/Valid Handshaking Kernel Invocation Interface and revised the topic.
  • Revised Pipelined Kernels

Document Revision History for the FPGA Optimization Guide for Intel® oneAPI Toolkits

Most of the content in the Intel® oneAPI FPGA Handbook originally appeared in the FPGA Optimization Guide for Intel® oneAPI Toolkits.

Date Release Version Changes
July 2023 2023.2
  • Revised the note about SYCL streams support and mentioned about using sycl::ext::oneapi::experimental::printf for debugging kernels.
  • Updated all occurrences of -Xsno-interleaving=<global_memory_type> to -Xsno-interleaving=<global_memory_name>.
  • Revised the information in the following topics:
    • Optimization Targets
    • Minimum Latency Flow
    • Loop Analysis
    • Quartus (Static) Summary
    • Pipes
    • Simple Host-Device Streaming
    • Buffered Host-Device Streaming
  • Added the following new topics:
    • Generate Register Map Wrapper (-Xsregister-map-wrapper-type)
    • Maximum Throughput Without Area Optimization Heuristics Flow
    • Create a 2xclock Interface (-Xsuse-2xclock)
    • Host Pipes
    • Host Pipe Declaration
    • Host Pipe API
    • Host Pipes RTL Interfaces
March 2023 2023.1
  • Added max_reinvocation_delay loop attribute.
  • Updated the limitations of AC data types in Advantages and Limitations of Arbitrary Precision Data Types.
  • Added another option to the -Xshyper-optimized-handshaking compiler flag in Modify the Handshaking Protocol Between Clusters (-Xshyper-optimized-handshaking).
  • Updated the values of supported data types and math operations in Control Hardware Implementation of the Supported Data Types and Math Operations.
  • Rebranded Intel® Agilex™ as Intel Agilex® 7.
  • Added device_globals extension.
  • Added Minimum Latency Flow.
  • Added Optimization Levels.
  • Revised the information in Perform Kernel Computations Using Local or Private Memory.
  • Reorganized all extensions under FPGA Extensions.
  • Added examples of declaring ac_complex variables in Declare the ac_complex Data Type.
December 2022 2023.0
  • Revised all references to #include <CL/...> as #include <sycl/...>.
  • Revised all references to using namespace cl::sycl; as using namespace sycl;.
  • Revised all references to dpcpp compiler driver to icpx -fsycl.
  • Added a note about avoiding adding the result of the convert_to function to another ap_float variable in Conversion Rules for ap_float.
  • Added a note about constant propagation optimization technique in Operations with Explicit Precision Controls.
  • Added additional about values supported by N for the [[intel::num_simd_work_items(N)]] attribute in Specify Number of SIMD Work-Items.
  • Revised Latency Controls topic to include a section on using latency controls with stall-free loop.
  • Added information about ihc::FPsingle and ihc::FPdouble to Declare the ap_float Data Type and Additional Data Types Provided by the ap_float.hpp Header File.
  • Added new sections on explicit conversion functions in Declare the ac_fixed Data Type and Declare the ac_int Data Type topics.
  • Removed deprecation notice for hls_float data type renamed to ap_float.
  • Added additional information about using the Intel® oneAPI FPGA Reports tool in Review the Optimization Report (report.html).
September 2022 2022.3
  • Added a note about setting the safelen parameter with 0 or 1 in ivdep Attribute.
  • Added a note about applying the ivdep attribute to an array in ivdep Attribute.
  • Minor update to example code in max_interleaving Attribute.
  • Updated all images and made moderate updates in all topics in the Analyze the FPGA Early Image section.
  • Made minor updates in Pipes topic.
  • Updated Latency Controls (Beta) topic completely.
  • Added a note about using the buffer_location<index> on BSPs with heterogeneous memory support in combination with read-only cache in Partitioning Buffers Across Different Memory Types (Heterogeneous Memory).
  • Revised the guidance in Timing Failures.
  • Made minor revisions in Zero-Copy Memory Access and Prepinning Memory topics.
  • Added the following new topics:
    • System of Tasks (task_sequence) Extension
    • Task Functions
    • task_sequence Use Cases
April 2022 2022.2
  • Changed the document title Intel® oneAPI DPC++ FPGA Optimization Guide to FPGA Optimization Guide for Intel® oneAPI Toolkits.
  • Replaced all general references to DPC++ with SYCL.
  • Added new loop functions to the existing list in FPGA Loop Directives.
  • Added a new limitation and removed some existing limitations in Advantages and Limitations of Arbitrary Precision Data Types.
  • Replaced all references to https://hlslibs.org/ with a reference to the documentation at https://github.com/hlslibs/ac_types/blob/v3.7/pdfdocs/ac_datatypes_ref.pdf.
  • Made a minor update to the description in The pipe Class and its Use.
  • Modified all occurrences of [[cl::reqd_work_group_size(Z, Y, X)]] to [[sycl::reqd_work_group_size(Z, Y, X)]]. [[cl::reqd_work_group_size(Z, Y, X)]] is now deprecated.
  • Added the following new topics:
    • Control Hardware Implementation of the Supported Data Types and Math Functions (-Xsdsp-mode=<option>)
    • Latency Controls
Level Two Title