Updating all tutorials that require USM support with error messages in (oneapi-src#648)

CMakeLists.txt if they select a board without USM support.
Also added a method to override this check for custom boards.
Added clearler instructions in the READMEs of these designs on the
limitations to USM and how to override the check for custom BSPs.

Author: tyoungsc

DirectProgramming/DPC++FPGA/Tutorials/DesignPatterns/buffered_host_streaming/README.md

@@ -13,7 +13,7 @@ The [oneAPI Programming Guide](https://software.intel.com/en-us/oneapi-programmi
 | What you will learn               | How to optimally stream data between the host and device to maximize throughput
 | Time to complete                  | 45 minutes
 
-_Notice: SYCL USM host allocations (and therefore this tutorial) are only supported for the Intel® FPGA PAC D5005 (with Intel Stratix® 10 SX)_
+*Notice: SYCL USM host allocations (and therefore this tutorial) are only supported for the Intel&reg; FPGA PAC D5005 (with Intel Stratix&reg; 10 SX) with USM support (i.e., intel_s10sx_pac:pac_s10_usm)* <br/>
 _Notice: This tutorial demonstrates an implementation of host streaming that will be supplanted by better techniques in a future release. See the [Drawbacks and Future Work](#drawbacks-and-future-work)_
 
 ## Purpose
@@ -114,7 +114,7 @@ When compiling for FPGA hardware, it is recommended to increase the job timeout
    ```
    You can also compile for a custom FPGA platform with SYCL USM support. Ensure that the board support package is installed on your system. Then run `cmake` using the command:
    ```
-   cmake .. -DFPGA_BOARD=<board-support-package>:<board-variant>
+   cmake .. -DFPGA_BOARD=<board-support-package>:<board-variant> -DUSM_HOST_ALLOCATIONS_ENABLED=1
    ```
 
 2. Compile the design through the generated `Makefile`. The following build targets are provided, matching the recommended development flow:
@@ -146,7 +146,7 @@ When compiling for FPGA hardware, it is recommended to increase the job timeout
    ```
    You can also compile for a custom FPGA platform with SYCL USM support. Ensure that the board support package is installed on your system. Then run `cmake` using the command:
    ```
-   cmake -G "NMake Makefiles" .. -DFPGA_BOARD=<board-support-package>:<board-variant>
+   cmake -G "NMake Makefiles" .. -DFPGA_BOARD=<board-support-package>:<board-variant> -DUSM_HOST_ALLOCATIONS_ENABLED=1
    ```
 
 2. Compile the design through the generated `Makefile`. The following build targets are provided, matching the recommended development flow:

DirectProgramming/DPC++FPGA/Tutorials/DesignPatterns/buffered_host_streaming/src/CMakeLists.txt

@@ -7,8 +7,22 @@ set(EMULATOR_TARGET ${TARGET_NAME}.fpga_emu)
 set(FPGA_TARGET ${TARGET_NAME}.fpga)
 set(REPORTS_TARGET ${TARGET_NAME}_report)
 
-# USM is only supported on the PAC S10 board
-set(FPGA_BOARD "intel_s10sx_pac:pac_s10_usm")
+# FPGA board selection
+if(NOT DEFINED FPGA_BOARD)
+    set(FPGA_BOARD "intel_s10sx_pac:pac_s10_usm")
+    message(STATUS "FPGA_BOARD was not specified.\
+                    \nConfiguring the design to run on the default FPGA board ${FPGA_BOARD} (Intel(R) PAC with Intel Stratix(R) 10 SX FPGA with USM support). \
+                    \nPlease refer to the README for information on board selection.")
+else()
+    message(STATUS "Configuring the design to run on FPGA board ${FPGA_BOARD}")
+endif()
+
+# this tutorial requires USM host allocations. Check the BSP name (which should contain the text 'usm')
+# to ensure the BSP has the required support. Allow the user to define USM_HOST_ALLOCATIONS_ENABLED
+# to override this check (e.g., cmake .. -DUSM_HOST_ALLOCATIONS_ENABLED=1)
+if(NOT FPGA_BOARD MATCHES ".usm.*" AND NOT DEFINED USM_HOST_ALLOCATIONS_ENABLED)
+    message(FATAL_ERROR "This tutorial requires a BSP that has USM host allocations enabled")
+endif()
 
 if(UNIX)
     set(THREAD_FLAG "-lpthread")

DirectProgramming/DPC++FPGA/Tutorials/DesignPatterns/simple_host_streaming/README.md

@@ -13,8 +13,8 @@ The [oneAPI Programming Guide](https://software.intel.com/en-us/oneapi-programmi
 | What you will learn               | How to achieve low-latency host-device streaming while maintaining throughput
 | Time to complete                  | 45 minutes
 
-_Notice: SYCL USM host allocations (and therefore this tutorial) are only supported for the Intel® FPGA PAC D5005 (with Intel Stratix® 10 SX)_
-_Notice: This tutorial demonstrates an implementation of host streaming that will be supplanted by better techniques in a future release. See the [Drawbacks and Future Work](#drawbacks-and-future-work)_
+*Notice: SYCL USM host allocations (and therefore this tutorial) are only supported for the Intel&reg; FPGA PAC D5005 (with Intel Stratix&reg; 10 SX) with USM support (i.e., intel_s10sx_pac:pac_s10_usm)* <br/>
+*Notice: This tutorial demonstrates an implementation of host streaming that will be supplanted by better techniques in a future release. See the [Drawbacks and Future Work](#drawbacks-and-future-work)*
 
 ## Purpose
 The purpose of this tutorial is to show you how to take advantage of SYCL USM host allocations and zero-copy host memory to implement a streaming host-device design with low latency and high throughput. Before starting this tutorial, we recommend first reviewing the **Pipes** (pipes) and **Zero-Copy Data Transfer** (zero_copy_data_transfer) FPGA tutorials, which will teach you more about SYCL pipes and SYCL USM and zero-copy data transfers, respectively.
@@ -113,7 +113,7 @@ When compiling for FPGA hardware, it is recommended to increase the job timeout
    ```
    You can also compile for a custom FPGA platform with SYCL USM support. Ensure that the board support package is installed on your system. Then run `cmake` using the command:
    ```
-   cmake .. -DFPGA_BOARD=<board-support-package>:<board-variant>
+   cmake .. -DFPGA_BOARD=<board-support-package>:<board-variant> -DUSM_HOST_ALLOCATIONS_ENABLED=1
    ```
 
 2. Compile the design through the generated `Makefile`. The following build targets are provided, matching the recommended development flow:
@@ -144,7 +144,7 @@ When compiling for FPGA hardware, it is recommended to increase the job timeout
    ```
    You can also compile for a custom FPGA platform with SYCL USM support. Ensure that the board support package is installed on your system. Then run `cmake` using the command:
    ```
-   cmake -G "NMake Makefiles" .. -DFPGA_BOARD=<board-support-package>:<board-variant>
+   cmake -G "NMake Makefiles" .. -DFPGA_BOARD=<board-support-package>:<board-variant> -DUSM_HOST_ALLOCATIONS_ENABLED=1
    ```
 
 2. Compile the design through the generated `Makefile`. The following build targets are provided, matching the recommended development flow:

DirectProgramming/DPC++FPGA/Tutorials/DesignPatterns/simple_host_streaming/src/CMakeLists.txt

@@ -7,8 +7,22 @@ set(EMULATOR_TARGET ${TARGET_NAME}.fpga_emu)
 set(FPGA_TARGET ${TARGET_NAME}.fpga)
 set(REPORTS_TARGET ${TARGET_NAME}_report)
 
-# USM is only supported on the PAC S10 board
-set(FPGA_BOARD "intel_s10sx_pac:pac_s10_usm")
+# FPGA board selection
+if(NOT DEFINED FPGA_BOARD)
+    set(FPGA_BOARD "intel_s10sx_pac:pac_s10_usm")
+    message(STATUS "FPGA_BOARD was not specified.\
+                    \nConfiguring the design to run on the default FPGA board ${FPGA_BOARD} (Intel(R) PAC with Intel Stratix(R) 10 SX FPGA with USM support). \
+                    \nPlease refer to the README for information on board selection.")
+else()
+    message(STATUS "Configuring the design to run on FPGA board ${FPGA_BOARD}")
+endif()
+
+# this tutorial requires USM host allocations. Check the BSP name (which should contain the text 'usm')
+# to ensure the BSP has the required support. Allow the user to define USM_HOST_ALLOCATIONS_ENABLED
+# to override this check (e.g., cmake .. -DUSM_HOST_ALLOCATIONS_ENABLED=1)
+if(NOT FPGA_BOARD MATCHES ".usm.*" AND NOT DEFINED USM_HOST_ALLOCATIONS_ENABLED)
+    message(FATAL_ERROR "This tutorial requires a BSP that has USM host allocations enabled")
+endif()
 
 # This is a Windows-specific flag that enables exception handling in host code
 if(WIN32)

DirectProgramming/DPC++FPGA/Tutorials/DesignPatterns/zero_copy_data_transfer/README.md

@@ -13,7 +13,7 @@ The [oneAPI Programming Guide](https://software.intel.com/en-us/oneapi-programmi
 | What you will learn               | How to use SYCL USM host allocations for the FPGA
 | Time to complete                  | 15 minutes
 
-_Notice: SYCL USM host allocations (and therefore this tutorial) are only supported for the Intel® FPGA PAC D5005 (with Intel Stratix® 10 SX)_
+*Notice: SYCL USM host allocations (and therefore this tutorial) are only supported for the Intel® FPGA PAC D5005 (with Intel Stratix® 10 SX) with USM support (i.e., intel_s10sx_pac:pac_s10_usm)*
 
 ## Purpose
 The purpose of this tutorial is to show you how to take advantage of zero-copy host memory for the FPGA to improve the performance of your design. On FPGA, DPC++ implements all host and shared allocations as *zero-copy* data in host memory. This means that the FPGA will access the data directly over PCIe, which can improve performance in cases where there is little or no temporal reuse of data in the FPGA kernel. This tutorial includes two different kernels: one using traditional SYCL buffers (`src/buffer_kernel.hpp`) and one using USM host allocations (`src/restricted_usm_kernel.hpp`) that takes advantage of zero-copy host memory. Before completing this tutorial, it is suggested you review the **Explicit USM** (explicit_usm) tutorial.
@@ -78,7 +78,7 @@ When compiling for FPGA hardware, it is recommended to increase the job timeout
    ```
    You can also compile for a custom FPGA platform with SYCL USM support. Ensure that the board support package is installed on your system. Then run `cmake` using the command:
    ```
-   cmake .. -DFPGA_BOARD=<board-support-package>:<board-variant>
+   cmake .. -DFPGA_BOARD=<board-support-package>:<board-variant> -DUSM_HOST_ALLOCATIONS_ENABLED=1
    ```
 
 2. Compile the design through the generated `Makefile`. The following build targets are provided, matching the recommended development flow:
@@ -111,7 +111,7 @@ When compiling for FPGA hardware, it is recommended to increase the job timeout
    ```
    You can also compile for a custom FPGA platform with SYCL USM support. Ensure that the board support package is installed on your system. Then run `cmake` using the command:
    ```
-   cmake -G "NMake Makefiles" .. -DFPGA_BOARD=<board-support-package>:<board-variant>
+   cmake -G "NMake Makefiles" .. -DFPGA_BOARD=<board-support-package>:<board-variant> -DUSM_HOST_ALLOCATIONS_ENABLED=1
    ```
 
 2. Compile the design through the generated `Makefile`. The following build targets are provided, matching the recommended development flow:

DirectProgramming/DPC++FPGA/Tutorials/DesignPatterns/zero_copy_data_transfer/src/CMakeLists.txt

@@ -7,8 +7,22 @@ set(EMULATOR_TARGET ${TARGET_NAME}.fpga_emu)
 set(FPGA_TARGET ${TARGET_NAME}.fpga)
 set(REPORTS_TARGET ${TARGET_NAME}_report)
 
-# USM is only supported on the PAC S10 board
-set(FPGA_BOARD "intel_s10sx_pac:pac_s10_usm")
+# FPGA board selection
+if(NOT DEFINED FPGA_BOARD)
+    set(FPGA_BOARD "intel_s10sx_pac:pac_s10_usm")
+    message(STATUS "FPGA_BOARD was not specified.\
+                    \nConfiguring the design to run on the default FPGA board ${FPGA_BOARD} (Intel(R) PAC with Intel Stratix(R) 10 SX FPGA with USM support). \
+                    \nPlease refer to the README for information on board selection.")
+else()
+    message(STATUS "Configuring the design to run on FPGA board ${FPGA_BOARD}")
+endif()
+
+# this tutorial requires USM host allocations. Check the BSP name (which should contain the text 'usm')
+# to ensure the BSP has the required support. Allow the user to define USM_HOST_ALLOCATIONS_ENABLED
+# to override this check (e.g., cmake .. -DUSM_HOST_ALLOCATIONS_ENABLED=1)
+if(NOT FPGA_BOARD MATCHES ".usm.*" AND NOT DEFINED USM_HOST_ALLOCATIONS_ENABLED)
+    message(FATAL_ERROR "This tutorial requires a BSP that has USM host allocations enabled")
+endif()
 
 # This is a Windows-specific flag that enables exception handling in host code
 if(WIN32)