FPGA: Batch PR - sim support - selectors update - readme rework

DirectProgramming/C++SYCL/DenseLinearAlgebra/simple-add/README.md

@@ -25,6 +25,15 @@ USM, buffer, accessor, kernel, and command groups.
 | Hardware           | GEN9 or newer <br> Intel® Programmable Acceleration Card with Intel® Arria® 10 GX FPGA (Intel® PAC with Intel® Arria® 10 GX FPGA)
 | Software           | Intel® oneAPI DPC++/C++ Compiler
 
+> **Note**: Even though the Intel DPC++/C++ OneAPI compiler is enough to compile for CPU, GPU, FPGA emulation, generating FPGA reports and generating RTL for FPGAs, there are extra software requirements for the FPGA simulation flow and FPGA compiles.
+>
+> For using the simulator flow, Intel® Quartus® Prime Pro Edition and one of the following simulators must be installed and accessible through your PATH:
+> - Questa*-Intel® FPGA Edition
+> - Questa*-Intel® FPGA Starter Edition
+> - ModelSim® SE
+>
+> When using the hardware compile flow, Intel® Quartus® Prime Pro Edition must be installed and accessible through your PATH.
+
 ## Key Implementation Details
 
 This sample provides examples of both buffers and USM implementations for simple side-by-side comparison.
@@ -111,19 +120,23 @@ To learn more about the extensions and how to configure the oneAPI environment,
    ```
    make fpga_emu
    ```
-2. Generate HTML performance reports.
+2. Compile for simulation (fast compile time, targets simulator FPGA device):
+   ```
+   make fpga_sim
+   ```
+3. Generate HTML performance reports.
    ```
    make report
    ```
    The reports reside at `simple-add_report.prj/reports/report.html`.
 
-3. Compile the program for FPGA hardware. (Compiling for hardware can take a long
+4. Compile the program for FPGA hardware. (Compiling for hardware can take a long
 time.)
    ```
    make fpga
    ```
 
-4. Clean the program. (Optional)
+5. Clean the program. (Optional)
    ```
    make clean
    ```
@@ -168,19 +181,23 @@ time.)
    ```
    nmake fpga_emu
    ```
-2. Generate HTML performance reports.
+2. Compile for simulation (fast compile time, targets simulator FPGA device):
+   ```
+   nmake fpga_sim
+   ```
+3. Generate HTML performance reports.
    ```
    nmake report
    ```
 The reports reside at `simple-add_report.prj/reports/report.html`.
 
-3. Compile the program for FPGA hardware. (Compiling for hardware can take a long
+4. Compile the program for FPGA hardware. (Compiling for hardware can take a long
 time.)
    ```
    nmake fpga
    ```
 
-4. Clean the program. (Optional)
+5. Clean the program. (Optional)
    ```
    nmake clean
    ```
@@ -216,7 +233,12 @@ If you receive an error message, troubleshoot the problem using the **Diagnostic
    ./simple-add-buffers.fpga_emu
    ./simple-add-usm.fpga_emu
    ```
-3. Run on FPGA hardware.
+3. Run on FPGA simulator.
+   ```
+   CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=1 ./simple-add-buffers.fpga_sim
+   CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=1 ./simple-add-usm.fpga_sim
+   ```
+4. Run on FPGA hardware.
    ```
    ./simple-add-buffers.fpga
    ./simple-add-usm.fpga
@@ -243,7 +265,14 @@ If you receive an error message, troubleshoot the problem using the **Diagnostic
    simple-add-buffers.fpga_emu.exe
    simple-add-usm.fpga_emu.exe
    ```
-3. Run on FPGA hardware.
+3. Run on FPGA simulator.
+   ```
+   set CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=1
+   simple-add-buffers.fpga_sim.exe
+   simple-add-usm.fpga_sim.exe
+   set CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=
+   ```
+4. Run on FPGA hardware.
    ```
    simple-add-buffers.fpga.exe
    simple-add-usm.fpga.exe

DirectProgramming/C++SYCL/DenseLinearAlgebra/simple-add/src/CMakeLists.txt

@@ -48,24 +48,33 @@ add_custom_target(cpu-gpu DEPENDS ${TARGET_NAME})
 
 # FPGA device selection
 if(NOT DEFINED FPGA_DEVICE)
-    set(FPGA_DEVICE "intel_a10gx_pac:pac_a10")
+    if(DEFINED USM AND (NOT(USM EQUAL 0)))
+        set(FPGA_DEVICE "intel_s10sx_pac:pac_s10_usm")
+        set(DEFAULT_BOARD_STR "Intel Stratix(R) 10 SX with USM support")
+    else()
+        set(FPGA_DEVICE "intel_a10gx_pac:pac_a10")
+        set(DEFAULT_BOARD_STR "Intel Arria(R) 10 GX")
+    endif()
     message(STATUS "FPGA_DEVICE was not specified.\
-                    \nConfiguring the design to run on the default FPGA device ${FPGA_DEVICE} (Intel(R) PAC with Intel Arria(R) 10 GX FPGA). \
-                    \nPlease refer to the README for information on device selection.")
+                \nConfiguring the design to run on the default FPGA board ${FPGA_DEVICE} (Intel(R) PAC with ${DEFAULT_BOARD_STR} FPGA). \
+                \nPlease refer to the README for information on board selection.")
 else()
     message(STATUS "Configuring the design to run on FPGA device ${FPGA_DEVICE}")
 endif()
 
 set(EMULATOR_TARGET ${TARGET_NAME}.fpga_emu)
+set(SIMULATOR_TARGET ${TARGET_NAME}.fpga_sim)
 set(FPGA_TARGET ${TARGET_NAME}.fpga)
 
 # A DPC++ ahead-of-time (AoT) compile processes the device code in two stages.
 # 1. The "compile" stage compiles the device code to an intermediate representation (SPIR-V).
 # 2. The "link" stage invokes the compiler's FPGA backend before linking.
 #    For this reason, FPGA backend flags must be passed as link flags in CMake.
-set(EMULATOR_COMPILE_FLAGS "-fsycl -Wall -fintelfpga ${WIN_FLAG} -DFPGA_EMULATOR")
+set(EMULATOR_COMPILE_FLAGS "-fsycl -fintelfpga -Wall ${WIN_FLAG} -DFPGA_EMULATOR")
 set(EMULATOR_LINK_FLAGS "-fsycl -fintelfpga")
-set(HARDWARE_COMPILE_FLAGS "-fsycl -Wall -fintelfpga ${WIN_FLAG}")
+set(SIMULATOR_COMPILE_FLAGS "-fsycl -fintelfpga -Wall ${WIN_FLAG} -Xssimulation -DFPGA_SIMULATOR")
+set(SIMULATOR_LINK_FLAGS "-fsycl -fintelfpga -Xssimulation -Xsghdl -Xstarget=${FPGA_DEVICE} ${USER_HARDWARE_FLAGS}")
+set(HARDWARE_COMPILE_FLAGS "-fsycl -fintelfpga -Wall ${WIN_FLAG} -DFPGA_HARDWARE")
 set(HARDWARE_LINK_FLAGS "-fsycl -fintelfpga -Xshardware -Xstarget=${FPGA_DEVICE} ${USER_HARDWARE_FLAGS}")
 # use cmake -D USER_HARDWARE_FLAGS=<flags> to set extra flags for FPGA backend compilation
 
@@ -82,6 +91,19 @@ set_target_properties(${EMULATOR_TARGET} PROPERTIES COMPILE_FLAGS "${EMULATOR_CO
 set_target_properties(${EMULATOR_TARGET} PROPERTIES LINK_FLAGS "${EMULATOR_LINK_FLAGS}")
 add_custom_target(fpga_emu DEPENDS ${EMULATOR_TARGET})
 
+###############################################################################
+### FPGA Simulator
+###############################################################################
+# To compile in a single command:
+#    icpx -fsycl -fintelfpga -Xssimulation -Xsghdl -Xstarget=<FPGA_DEVICE> -DFPGA_SIMULATOR <file>.cpp -o <file>.fpga_sim
+# CMake executes:
+#    [compile] icpx -fsycl -fintelfpga -Xssimulation -DFPGA_SIMULATOR -o <file>.cpp.o -c <file>.cpp
+#    [link]    icpx -fsycl -fintelfpga -Xssimulation -Xsghdl -Xstarget=<FPGA_DEVICE> <file>.cpp.o -o <file>.fpga_sim
+add_executable(${SIMULATOR_TARGET} ${SOURCE_FILE})
+set_target_properties(${SIMULATOR_TARGET} PROPERTIES COMPILE_FLAGS "${SIMULATOR_COMPILE_FLAGS}")
+set_target_properties(${SIMULATOR_TARGET} PROPERTIES LINK_FLAGS "${SIMULATOR_LINK_FLAGS}")
+add_custom_target(fpga_sim DEPENDS ${SIMULATOR_TARGET})
+
 ###############################################################################
 ### Generate Report
 ###############################################################################

DirectProgramming/C++SYCL/DenseLinearAlgebra/simple-add/src/simple-add-buffers.cpp

@@ -23,7 +23,7 @@
 #include <array>
 #include <iostream>
 
-#if FPGA || FPGA_EMULATOR
+#if FPGA_HARDWARE || FPGA_EMULATOR || FPGA_SIMULATOR
   #include <sycl/ext/intel/fpga_extensions.hpp>
 #endif
 
@@ -84,13 +84,16 @@ int main() {
   // Create device selector for the device of your interest.
 #if FPGA_EMULATOR
   // Intel extension: FPGA emulator selector on systems without FPGA card.
-  ext::intel::fpga_emulator_selector d_selector;
-#elif FPGA
+  auto selector = sycl::ext::intel::fpga_emulator_selector_v;
+#elif FPGA_SIMULATOR
+  // Intel extension: FPGA simulator selector on systems without FPGA card.
+  auto selector = sycl::ext::intel::fpga_simulator_selector_v;
+#elif FPGA_HARDWARE
   // Intel extension: FPGA selector on systems with FPGA card.
-  ext::intel::fpga_selector d_selector;
+  auto selector = sycl::ext::intel::fpga_selector_v;
 #else
   // The default device selector will select the most performant device.
-  auto d_selector{default_selector_v};
+  auto selector = default_selector_v;
 #endif
 
   // Create array objects with "array_size" to store data.
@@ -101,7 +104,7 @@ int main() {
   for (size_t i = 0; i < sequential.size(); i++) sequential[i] = value + i;
 
   try {
-    queue q(d_selector, exception_handler);
+    queue q(selector, exception_handler);
 
     // Print out the device information used for the kernel code.
     cout << "Running on device: "

DirectProgramming/C++SYCL/DenseLinearAlgebra/simple-add/src/simple-add-usm.cpp

@@ -23,7 +23,7 @@
 #include <array>
 #include <iostream>
 
-#if FPGA || FPGA_EMULATOR
+#if FPGA_HARDWARE || FPGA_EMULATOR || FPGA_SIMULATOR
   #include <sycl/ext/intel/fpga_extensions.hpp>
 #endif
 
@@ -75,13 +75,16 @@ int main() {
   // Create device selector for the device of your interest.
 #if FPGA_EMULATOR
   // Intel extension: FPGA emulator selector on systems without FPGA card.
-  ext::intel::fpga_emulator_selector selector;
-#elif FPGA
+  auto selector = sycl::ext::intel::fpga_emulator_selector_v;
+#elif FPGA_SIMULATOR
+  // Intel extension: FPGA simulator selector on systems without FPGA card.
+  auto selector = sycl::ext::intel::fpga_simulator_selector_v;
+#elif FPGA_HARDWARE
   // Intel extension: FPGA selector on systems with FPGA card.
-  ext::intel::fpga_selector selector;
+  auto selector = sycl::ext::intel::fpga_selector_v;
 #else
   // The default device selector will select the most performant device.
-  auto selector{default_selector_v};
+  auto selector = default_selector_v;
 #endif
 
   constexpr int value = 100000;

DirectProgramming/C++SYCL/DenseLinearAlgebra/vector-add/README.md

@@ -28,6 +28,15 @@ This sample provides example implementations of both Unified Shared Memory (USM)
 | Hardware                          | GEN9 or newer <br> Intel® Programmable Acceleration Card with Intel® Arria® 10 GX FPGA (Intel® PAC with Intel® Arria® 10 GX FPGA)
 | Software                          | Intel® oneAPI DPC++/C++ Compiler
 
+> **Note**: Even though the Intel DPC++/C++ OneAPI compiler is enough to compile for CPU, GPU, FPGA emulation, generating FPGA reports and generating RTL for FPGAs, there are extra software requirements for the FPGA simulation flow and FPGA compiles.
+>
+> For using the simulator flow, Intel® Quartus® Prime Pro Edition and one of the following simulators must be installed and accessible through your PATH:
+> - Questa*-Intel® FPGA Edition
+> - Questa*-Intel® FPGA Starter Edition
+> - ModelSim® SE
+>
+> When using the hardware compile flow, Intel® Quartus® Prime Pro Edition must be installed and accessible through your PATH.
+
 ## Key Implementation Details
 
 The basic SYCL implementation explained in the code includes device selector, USM, buffer, accessor, kernel, and command groups.
@@ -111,19 +120,23 @@ To learn more about the extensions and how to configure the oneAPI environment,
    ```
    make fpga_emu
    ```
-2. Generate HTML performance reports.
+2. Compile for simulation (fast compile time, targets simulator FPGA device):
+   ```
+   make fpga_sim
+   ```
+3. Generate HTML performance reports.
    ```
    make report
    ```
    The reports reside at `simple-add_report.prj/reports/report.html`.
 
-3. Compile the program for FPGA hardware. (Compiling for hardware can take a long
+4. Compile the program for FPGA hardware. (Compiling for hardware can take a long
 time.)
    ```
    make fpga
    ```
 
-4. Clean the program. (Optional)
+5. Clean the program. (Optional)
    ```
    make clean
    ```
@@ -168,19 +181,23 @@ time.)
    ```
    nmake fpga_emu
    ```
-2. Generate HTML performance reports.
+2. Compile for simulation (fast compile time, targets simulator FPGA device):
+   ```
+   nmake fpga_sim
+   ```
+3. Generate HTML performance reports.
    ```
    nmake report
    ```
 The reports reside at `simple-add_report.prj/reports/report.html`.
 
-3. Compile the program for FPGA hardware. (Compiling for hardware can take a long
+4. Compile the program for FPGA hardware. (Compiling for hardware can take a long
 time.)
    ```
    nmake fpga
    ```
 
-4. Clean the program. (Optional)
+5. Clean the program. (Optional)
    ```
    nmake clean
    ```
@@ -221,7 +238,12 @@ The source files (`vector-add-buffers.cpp` and `vector-add-usm.cpp`) specify the
     ./vector-add-buffers.fpga_emu
     ./vector-add-usm.fpga_emu
     ```
-3. Run on FPGA hardware.
+3. Run on FPGA simulator.
+   ```
+   CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=1 ./vector-add-buffers.fpga_sim
+   CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=1 ./vector-add-usm.fpga_sim
+   ```
+4. Run on FPGA hardware.
     ```
     ./vector-add-buffers.fpga
     ./vector-add-usm.fpga
@@ -248,7 +270,14 @@ The source files (`vector-add-buffers.cpp` and `vector-add-usm.cpp`) specify the
     vector-add-buffers.fpga_emu.exe
     vector-add-usm.fpga_emu.exe
     ```
-3. Run on FPGA hardware.
+3. Run on FPGA simulator.
+   ```
+   set CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=1
+   vector-add-buffers.fpga_sim.exe
+   vector-add-usm.fpga_sim.exe
+   set CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=
+   ```
+4. Run on FPGA hardware.
     ```
     vector-add-buffers.fpga.exe
     vector-add-usm.fpga.exe

DirectProgramming/C++SYCL/DenseLinearAlgebra/vector-add/src/CMakeLists.txt

@@ -48,24 +48,34 @@ add_custom_target(cpu-gpu DEPENDS ${TARGET_NAME})
 
 # FPGA device selection
 if(NOT DEFINED FPGA_DEVICE)
-    set(FPGA_DEVICE "intel_a10gx_pac:pac_a10")
+    if(DEFINED USM AND (NOT(USM EQUAL 0)))
+        set(FPGA_DEVICE "intel_s10sx_pac:pac_s10_usm")
+        set(DEFAULT_BOARD_STR "Intel Stratix(R) 10 SX with USM support")
+    else()
+        set(FPGA_DEVICE "intel_a10gx_pac:pac_a10")
+        set(DEFAULT_BOARD_STR "Intel Arria(R) 10 GX")
+    endif()
     message(STATUS "FPGA_DEVICE was not specified.\
-                    \nConfiguring the design to run on the default FPGA device ${FPGA_DEVICE} (Intel(R) PAC with Intel Arria(R) 10 GX FPGA). \
-                    \nPlease refer to the README for information on device selection.")
+                \nConfiguring the design to run on the default FPGA board ${FPGA_DEVICE} (Intel(R) PAC with ${DEFAULT_BOARD_STR} FPGA). \
+                \nPlease refer to the README for information on board selection.")
 else()
     message(STATUS "Configuring the design to run on FPGA device ${FPGA_DEVICE}")
 endif()
 
+
 set(EMULATOR_TARGET ${TARGET_NAME}.fpga_emu)
+set(SIMULATOR_TARGET ${TARGET_NAME}.fpga_sim)
 set(FPGA_TARGET ${TARGET_NAME}.fpga)
 
 # A DPC++ ahead-of-time (AoT) compile processes the device code in two stages.
 # 1. The "compile" stage compiles the device code to an intermediate representation (SPIR-V).
 # 2. The "link" stage invokes the compiler's FPGA backend before linking.
 #    For this reason, FPGA backend flags must be passed as link flags in CMake.
-set(EMULATOR_COMPILE_FLAGS "-fsycl -Wall -fintelfpga -DFPGA_EMULATOR ${WIN_FLAG}")
+set(EMULATOR_COMPILE_FLAGS "-fsycl -fintelfpga -Wall ${WIN_FLAG} -DFPGA_EMULATOR")
 set(EMULATOR_LINK_FLAGS "-fsycl -fintelfpga")
-set(HARDWARE_COMPILE_FLAGS "-fsycl -Wall -fintelfpga -DFPGA ${WIN_FLAG}")
+set(SIMULATOR_COMPILE_FLAGS "-fsycl -fintelfpga -Wall ${WIN_FLAG} -Xssimulation -DFPGA_SIMULATOR")
+set(SIMULATOR_LINK_FLAGS "-fsycl -fintelfpga -Xssimulation -Xsghdl -Xstarget=${FPGA_DEVICE} ${USER_HARDWARE_FLAGS}")
+set(HARDWARE_COMPILE_FLAGS "-fsycl -fintelfpga -Wall ${WIN_FLAG} -DFPGA_HARDWARE")
 set(HARDWARE_LINK_FLAGS "-fsycl -fintelfpga -Xshardware -Xstarget=${FPGA_DEVICE} ${USER_HARDWARE_FLAGS}")
 # use cmake -D USER_HARDWARE_FLAGS=<flags> to set extra flags for FPGA backend compilation
 
@@ -82,6 +92,19 @@ set_target_properties(${EMULATOR_TARGET} PROPERTIES COMPILE_FLAGS "${EMULATOR_CO
 set_target_properties(${EMULATOR_TARGET} PROPERTIES LINK_FLAGS "${EMULATOR_LINK_FLAGS}")
 add_custom_target(fpga_emu DEPENDS ${EMULATOR_TARGET})
 
+###############################################################################
+### FPGA Simulator
+###############################################################################
+# To compile in a single command:
+#    icpx -fsycl -fintelfpga -Xssimulation -Xsghdl -Xstarget=<FPGA_DEVICE> -DFPGA_SIMULATOR <file>.cpp -o <file>.fpga_sim
+# CMake executes:
+#    [compile] icpx -fsycl -fintelfpga -Xssimulation -DFPGA_SIMULATOR -o <file>.cpp.o -c <file>.cpp
+#    [link]    icpx -fsycl -fintelfpga -Xssimulation -Xsghdl -Xstarget=<FPGA_DEVICE> <file>.cpp.o -o <file>.fpga_sim
+add_executable(${SIMULATOR_TARGET} ${SOURCE_FILE})
+set_target_properties(${SIMULATOR_TARGET} PROPERTIES COMPILE_FLAGS "${SIMULATOR_COMPILE_FLAGS}")
+set_target_properties(${SIMULATOR_TARGET} PROPERTIES LINK_FLAGS "${SIMULATOR_LINK_FLAGS}")
+add_custom_target(fpga_sim DEPENDS ${SIMULATOR_TARGET})
+
 ###############################################################################
 ### Generate Report
 ###############################################################################