[SYCL][FPGA] Support Intel FPGA simulator device selector

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/include/sycl/ext/intel/fpga_device_selector.hpp

@@ -55,6 +55,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/feature_test.hpp.in

@@ -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