[SYCL][FPGA] Support Intel FPGA simulator device selector (#6715)

Create **fpga_simulator_selector** to be used to select the FPGA
simulator device. This assumes that the user has compiled their program
with -Xssimulation (as well as -fintelfpga) to prepare for the
simulator.

An object of class fpga_simulator_selector must be constructed early in
the execution of the host program in order to make the simulator
available at runtime.

The current implementation has the effect that if an object of class
sycl::ext::intel::fpga_simulator_selector is defined, FPGA hardware
devices selected using sycl::ext::intel::fpga_selector will select
simulator devices. This will be documented in the release notes and the
specification. We expect this behaviour to be eliminated in the future.

Author: mendell27

sycl/doc/extensions/supported/sycl_ext_intel_fpga_device_selector.asciidoc

@@ -0,0 +1,125 @@
+= sycl_ext_intel_fpga_device_selector
+
+:source-highlighter: coderay
+:coderay-linenums-mode: table
+
+// This section needs to be after the document title.
+:doctype: book
+:toc2:
+:toc: left
+:encoding: utf-8
+:lang: en
+:dpcpp: pass:[DPC++]
+
+// Set the default source code type in this document to C++,
+// for syntax highlighting purposes.  This is needed because
+// docbook uses c++ and html5 uses cpp.
+:language: {basebackend@docbook:c++:cpp}
+
+
+== Notice
+
+[%hardbreaks]
+Copyright (C) 2022-2022 Intel Corporation.  All rights reserved.
+
+Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are trademarks
+of The Khronos Group Inc.  OpenCL(TM) is a trademark of Apple Inc. used by
+permission by Khronos.
+
+
+== Contact
+
+To report problems with this extension, please open a new issue at:
+
+https://github.com/intel/llvm/issues
+
+
+== Dependencies
+
+This extension is written against the SYCL 2020 revision 5 specification.  All
+references below to the "core SYCL specification" or to section numbers in the
+SYCL specification refer to that revision.
+
+== Status
+
+This extension is implemented and fully supported by {dpcpp}.
+
+[NOTE]
+====
+This extension is currently implemented in {dpcpp} only for FPGA devices.
+In the {dpcpp} implementation, the application must be built with
+"-Xshardware" in order to use an FPGA hardware device.
+In the {dpcpp} implementation, the application must be built with
+"-Xssimulation" in order to use an FPGA simulator device.
+====
+
+
+== Overview
+
+This extension provides selectors to choose between FPGA hardware devices, FPGA
+simulator devices, and FPGA emulator devices. The current implementation is
+based on the platform name.  This is useful in the most common case when the
+user has one FPGA board installed in their system (one device per platform).
+
+To use these selectors, add
+....
+#include <sycl/ext/intel/fpga_device_selector.hpp>
+....
+to your source code.
+
+
+== Specification
+
+=== Feature test macro
+
+This extension provides a feature-test macro as described in the core SYCL
+specification.  An implementation supporting this extension must predefine the
+macro `SYCL_EXT_INTEL_FPGA_DEVICE_SELECTOR` to one of the values defined in the table
+below.  Applications can test for the existence of this macro to determine if
+the implementation supports this feature, or applications can test the macro's
+value to determine which of the extension's features the implementation
+supports.
+
+[%header,cols="1,5"]
+|===
+|Value
+|Description
+
+|1
+|Initial version of this extension. Base features are supported.
+
+|2
+|fpga_simulator_selector added.
+|===
+
+=== Select FPGA hardware device
+....
+// select FPGA hardware device
+sycl::queue deviceQueue{sycl::ext::intel::fpga_selector{}};
+....
+
+=== Select FPGA simulator device
+....
+// select FPGA simulator device
+sycl::queue deviceQueue{sycl::ext::intel::fpga_simulator_selector{}};
+....
+
+[NOTE]
+====
+Added in version 2 of this extension.
+====
+
+=== Select FPGA emulator device
+....
+// select FPGA emulator device
+sycl::queue deviceQueue{sycl::ext::intel::fpga_emulator_selector{}};
+....
+
+== Implementation notes
+
+The current implementation has a restriction on the use of
+`fpga_simulator_selector`.  If an object of `fpga_simulator_selector` is
+defined in the application, FPGA hardware devices selected using
+`fpga_selector` will select a simulator device. This behaviour is expected to
+be eliminated in the future.
+

sycl/doc/extensions/supported/sycl_ext_intel_fpga_device_selector.md

@@ -56,6 +56,18 @@ class fpga_emulator_selector : public platform_selector {
   fpga_emulator_selector() : platform_selector(EMULATION_PLATFORM_NAME) {}
 };
 
+class fpga_simulator_selector : public fpga_selector {
+public:
+  fpga_simulator_selector() {
+    // Tell the runtime to use a simulator device rather than hardware
+#ifdef _WIN32
+    _putenv_s("CL_CONTEXT_MPSIM_DEVICE_INTELFPGA", "1");
+#else
+    setenv("CL_CONTEXT_MPSIM_DEVICE_INTELFPGA", "1", 0);
+#endif
+  }
+};
+
 } // namespace intel
 } // namespace ext
 

sycl/include/sycl/ext/intel/fpga_device_selector.hpp

@@ -62,7 +62,7 @@ __SYCL_INLINE_VER_NAMESPACE(_V1) {
 #define SYCL_EXT_INTEL_EXTENDED_ATOMICS 1
 #endif
 #endif
-#define SYCL_EXT_INTEL_FPGA_DEVICE_SELECTOR 1
+#define SYCL_EXT_INTEL_FPGA_DEVICE_SELECTOR 2
 #define SYCL_EXT_INTEL_FPGA_LSU 1
 #define SYCL_EXT_INTEL_FPGA_REG 1
 #define SYCL_EXT_INTEL_KERNEL_ARGS_RESTRICT 1