Intel® oneAPI DPC++ FPGA Workflows on Third-Party IDEs

1. Introduction

Intel® oneAPI tools integrate with third-party integrated development environments (IDEs) on Linux* and Windows* to provide a seamless GUI experience for software development. Access the entire IDE suite using Eclipse* on Linux* and Visual Studio* on Windows*. After installing the Intel® oneAPI tools, select tools integrate into the IDE menu.

NOTE: For FPGA development with Visual Studio Code on Linux*, refer to Intel® oneAPI DPC++ FPGA Development with Sample Browser Extension for Visual Studio Code on Linux.

1.1 Compilation Stages

Both the Eclipse and Visual Studio IDEs perform DPC++ compilation in two stages — the compile stage and the link stage. You might need to pass different compiler arguments to different stages, as follows:

1.2 Compilation Targets

In both the Eclipse and Visual Studio IDEs, by default, all projects support Debug and Release compile targets, and the purpose of these two targets can be confusing due to the presence of multiple levels of debug information in FPGA compiles. The behavior of the compilation targets are as follows:

• Debug Target: Adds host code debug information. If you use the emulator flow, the kernel code also contains debug information. If you want to collect further information about the kernel code execution on an FPGA hardware, refer to the Intel® FPGA Dynamic Profiler for DPC++ section in the Intel® oneAPI DPC++ FPGA Optimization Guide. 
• Release Target: Removes host code debug information. If you target the FPGA optimization reports, switching from the Debug to Release target has no impact unless you are further compiling the intermittent image to a full hardware executable (which loses host-side debug information in the Release mode).

NOTE: The Release target does not remove the internal debug data used by the FPGA optimization reports, so you can still review the reports. 

2. FPGA Workflows in Eclipse*

NOTE: This section assumes you have completed performing instructions from Build and Run a Sample Project Using Eclipse*.

NOTE: Compilation using the Intel® oneAPI DPC++/C++ Compiler in Eclipse* works only if Eclipse is launched from a terminal in which the setvars.sh script has already been run.

2.1 Build FPGA Executables for Emulator and Hardware

FPGA development supports emulation and hardware compilation modes. For detailed information, refer to Types of DPC++ FPGA Compilation in the Intel® oneAPI Programming Guide.       

• Emulation build is fast. Use it to achieve a functionally correct result or to debug without having an actual FPGA hardware.
• Hardware build may take a longer time to complete. Use it for performance tuning and production builds.

There are several supported project types in Eclipse* that you can use for your Data Parallel C++ project, such as:

• Makefile-based project
• CMake-based project
• C++-managed build project

Intel® recommends the Makefile and the CMake-based flows.

2.1.1 Create a New CMake Project to Target FPGA Executables

Intel® recommends that you create your new CMake project using a sample or an example design, as described in Create a Project Using an FPGA Example Design or Tutorial​. This way, you need not create FPGA-specific targets. Instead, you can adjust the existing targets to your needs. If you want to create a clean CMake project, you can do so through the File > New > C/C++ Project > CMake Project.

2.1.2 Create a New Makefile Project to Target FPGA Executables

To create a new Makefile project, perform these steps:

1. Under File > New > C/C++ Project > C++ Managed Build, select the Makefile Project tab.
2. Ensure that you have selected the Intel® oneAPI DPC++/C++ Compiler toolchain.
3. Add targets to the Makefile to compile for various FPGA devices.
4. If you want to iterate over the FPGA Optimization Report step, add the target to the FPGA settings of the project, as described in Generate FPGA Optimization Report in CMake and Makefile Projects, to allow you to re-run this step with the press of a button.

2.1.3 Create a New C++ Managed Build Project to Target FPGA Executables

When creating a new project, make sure you select C++ Managed Build and use the Intel® oneAPI DPC++/C++ Compiler toolchain. Then, follow these instructions to create default build configurations, including corresponding compiler options, to simplify the process of building FPGA executables:

1. Create build configurations using the following steps:
   1. Open the Project menu.
   2. Select Build Configurations > Create FPGA Build Configs menu option.
   3. Click OK to acknowledge the pop-up dialog box message. This leads to the creation of FPGA build configurations.
2. Set the active build configuration using the following steps:
   1. Open the Project menu.
   2. Select Build Configurations > Set Active menu option and build an executable either for FPGA emulator or FPGA hardware.
      • Select FPGA_Emulator_Debug to build an FPGA emulator executable.
      • Select FPGA_Hardware_Release to build an FPGA hardware executable.
3. Select Project > Build Project menu option to build the project.

NOTE: The Project menu options are also available by right-clicking on the project.

NOTE: To add compiler options, go to Project > Properties > C++ Build > Settings > Tool Settings > Linker step > Miscellaneous tab. Refer to the Add Build Options section for more information.

2.2 Generate and Analyze the FPGA Optimization Report

After you generate the report using one of the following methods, it is displayed in a tab within the Eclipse* editor. For more information about the optimization reports, refer to the Intel® oneAPI DPC++ FPGA Optimization Guide.

2.2.1 Generate FPGA Optimization Report in CMake and Makefile Projects

Generate the FPGA optimization report using one of the following methods:

• Click the Generate FPGA Optimization Reports button in the Eclipse toolbar or use the Ctrl-8 shortcut key. If this is the first time you are generating reports for this project, this button prompts you to fill in the Optimization report build command and Optimization report folder entries in the project’s FPGA Settings. The former should include the target that must be run to generate the reports, for example, make report, while the latter needs to contain the path to the directory in which the reports are created, for example, sample.prj/reports. Once you fill these entries, you can use the toolbar button directly for all subsequent iterations over the optimization reports.

• Build the reports' target (make report) directly, and then locate the ide_report.html file in the project directory’s reports folder. Double-clicking this HTML file launches the report in the IDE.

2.2.2 Generate FPGA Optimization Report in C++ Managed Projects

Generate the FPGA optimization report using one of the following methods:

• Select Project > Generate FPGA Optimization Reports menu option.
• Click the Generate FPGA Optimization Reports icon in the Eclipse* toolbar or use the Ctrl-8 shortcut key.
• Select Generate FPGA Optimization Reports in the context-sensitive menu.

NOTE: All three methods are available only if the correct project build configuration or the corresponding compiler option is selected.

2.3 Create a Project Using an FPGA Example Design or Tutorial

You can create new projects using pre-designed FPGA example designs and tutorials. Follow these steps to create a project based on a sample:

1. Create a new project using File > New > Browse Intel Samples.
2. Go to the Intel oneAPI Base Toolkit tab.
3. Locate FPGA example designs and tutorials as well as other DPC++ samples under FPGA.
4. Select the desired sample.

Once you launch the sample, if you build the sample project, an FPGA emulator executable is created. If you want to compile the design for a different target, you should first view the prepopulated targets in the Build Targets drop-down list in your project’s Build/Debug directory. If the desired target is not available in the drop-down list, view the build targets available in the Makefile in the Outline window.

2.3.1 Adjust the FPGA Board Used by the FPGA Sample

NOTE: Only some FPGA samples support running on different FPGA boards. Refer to the README file of the sample you are using for more information.

If the sample you are running supports changing the FPGA hardware board being compiled for by using the -DFPGA_BOARD CMake definition, you can pass this argument as follows:

1. Go to the Project > Properties menu option. The Properties dialog is launched.
2. In the C/C++ Build section, navigate to the Cmake4eclipse tab.
3. In the General tab, check the Force CMake to run with each build checkbox. You can uncheck this after your next build.
4. In the Host OS Overrides subsection, click the Add button to add a new definition to the CMake cache entries to create section.
5. Enter FPGA_BOARD as the variable name and the board you want as the value. For example, for some samples, you can enter as intel_s10sx_pac:pac_s10 to indicate the Intel® FPGA Programmable Acceleration Card D5005 FPGA board.

2.4 Add Build Options

2.4.1 Add Build Options to CMake or Makefile Projects

In CMake and Makefile projects, you can adjust the build options by modifying the underlying CMakeLists.txt or Makefile to add or remove options from the targets you want to adjust.

2.4.2 Add Build Options to C++ Managed Projects

You can add miscellaneous options to the compile as follows:

1. Go to the Project > Properties menu option. The Properties dialog is launched. Alternatively, use the context-sensitive menu.
2. In the C/C++ Build tab, go to the Settings subtab. The Tool Settings tab displays compile and link commands you are using. In this tab, you can add the command line options in the following manner:
   • Add options for the compile step in the Command Line tab of the Intel® oneAPI DPC++/C++ Compiler drop-down menu. In this tab, you can pass definitions, such as -DINTEL_FPGA.
   • Add options for the link step in the Miscellaneous section under the Linker drop-down menu. In this section, you can pass options for the FPGA compile, such as -Xsprofile.

3. FPGA Workflows in Microsoft Visual Studio*

Note: This section assumes you have already performed instructions listed in Build and Run a Sample Project Using Microsoft Visual Studio*.

3.1 Create a Project Using an FPGA Example Design or Tutorial

There are pre-designed FPGA example designs and tutorials that you can build and run in the Microsoft Visual Studio* IDE. Follow these steps to create a project based on a sample:

1. Go to Intel > Open an Intel oneAPI Sample menu option.
2. Navigate to the Intel oneAPI Base Toolkit tab.
3. Locate the FPGA samples under the FPGA subtab.
4. Select the desired sample.

Once the sample is launched, if you build the sample project, an FPGA emulator executable is created to run using the Visual Studio* IDE.

If you want to run a sample that is not in the FPGA folder, ensure that you set the FPGA-specific options, as described in Build FPGA Emulator Executables.

NOTE: In this release of Intel® oneAPI Base Toolkit, the FPGA emulation, reports, and hardware flow are supported.

3.2 Build FPGA Emulator Executables

1. Go to File > New > Project… drop-down menu.
2. Select the DPC++ tab if it is not already selected by default.
3. In the DPC++ tab, select DPC++ Console Application to create the project.
4. To run this default example to create an FPGA Emulator executable, perform the following steps:
   1. Go to Project > Properties menu.
   2. Navigate to the DPC++ tab.
   3. In the General subtab, change the Perform ahead of time compilation for the FPGA setting to Yes.
   4. In the Command Line subtab, add -DINTEL_FPGA -DFPGA_EMULATOR option to the additional options.

NOTE: Extra command-line options are not required if the intel::fpga_emulator_selector is used by default.

3.3 Generate and Analyze the FPGA Optimization Report

Follow these steps to generate an optimization report in the Microsoft Visual Studio* IDE:

1. Ensure that the Perform offline (ahead of time) compilation for FPGA target option is set to Yes in the DPC++ > General tab of the project properties (this is already the case in all pre-designed FPGA samples).
2. Generate FPGA optimization reports using one of the following methods:
   • Select Project > Generate FPGA Optimization Reports menu option.
   • Click the Generate FPGA Optimization Reports icon in the Visual Studio* toolbar.
   • Select Generate FPGA Optimization Reports in the context-sensitive menu.

Once compilation finishes, the FPGA optimization reports open in the Visual Studio. If you want to open them in a browser or re-open them later, the report.html file is created in the x64/<Configuration_name>/<project_name>.proj/reports/ folder. You can open and view this file in most of the standard web browsers. For more information about the optimization reports, refer to the Intel® oneAPI DPC++ FPGA Optimization Guide.

3.4 Add Build Options

You can add miscellaneous options to the compile as follows:

1. Go to Project > Properties menu option. Properties dialog is launched.
2. Add the command line options in the following manner:
   • Add options for the compile step in the Command Line subtab of the DPC++ tab. In this tab, you can pass definitions such as -DINTEL_EMULATOR.

   • Add options for the link step in Pass additional options to device compilers in the General section under the Linker tab. Here, you can pass options such as -Xsprofile or -Xsfp-relaxed to the FPGA step of the compilation. A semicolon must separate the supplied options (for example, -Xsprofile;-Xsfp-relaxed).

References

• Explore DPC++ Through Intel® FPGA Code Samples
• Intel® oneAPI Visual Studio Samples Browser | oneAPI
• Intel® oneAPI Eclipse Samples Plugin | oneAPI
• Intel® oneAPI DPC++ FPGA Development with Sample Browser Extension for Visual Studio Code on Linux
• Intel® oneAPI Programming Guide
• Intel® oneAPI DPC++ FPGA Optimization Guide

Notice and Disclaimers

Intel® technologies may require enabled hardware, software or service activation.

No product or component can be absolutely secure.

Your costs and results may vary.

© Intel Corporation. Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries. Other names and brands may be claimed as the property of others.

No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document.

The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.

Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade.