[SYCL] Implement new env var SYCL_DEVICE_FILTER

sycl/doc/EnvironmentVariables.md

@@ -11,6 +11,7 @@ subject to change. Do not rely on these variables in production code.
 
 | Environment variable | Values | Description |
 | -------------------- | ------ | ----------- |
+| SYCL_DEVICE_TRIPLE | device_type[:backend:device_num] | Force SYCL RT to use the specified device with optional backend and device_num information. It can list any number of triples separated by commas. This env var affects all different device selectors and device discovery. When no device that can satisfy the triple, a heuristic will choose the device that has the closest match. Possible values of device_type are *,host,cpu,gpu,acc,*. Possible values of backend are opencl, level0, cuda. Device_num is an unsigned integer that indexes the enumeration of devices from get_device() call. Among triple entries, only the device_type is required. The other two entries, backend and device_num, are optional. For example, to use cpu and level0 gpu, one can set SYCL_DEVICE_TYPE=cpu,gpu:level0 |
 | SYCL_PI_TRACE | Described [below](#sycl_pi_trace-options)  | Enable specified level of tracing for PI. |
 | SYCL_BE | PI_OPENCL, PI_LEVEL_ZERO, PI_CUDA | Force SYCL RT to consider only devices of the specified backend during the device selection. |
 | SYCL_DEVICE_TYPE | One of: CPU, GPU, ACC, HOST | Force SYCL to use the specified device type. If unset, default selection rules are applied. If set to any unlisted value, this control has no effect. If the requested device type is not found, a `cl::sycl::runtime_error` exception is thrown. If a non-default device selector is used, a device must satisfy both the selector and this control to be chosen. This control only has effect on devices created with a selector. |

sycl/include/CL/sycl/triple.hpp

@@ -0,0 +1,64 @@
+//==-------------- triple.hpp - SYCL device triple descripter --------------==//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#pragma once
+
+#include <CL/sycl/backend_types.hpp>
+#include <CL/sycl/detail/defines.hpp>
+#include <CL/sycl/info/info_desc.hpp>
+
+#include <fstream>
+#include <iostream>
+#include <istream>
+#include <string>
+
+__SYCL_INLINE_NAMESPACE(cl) {
+namespace sycl {
+
+#define DEVICE_NUM_UNSPECIFIED -1
+
+struct triple {
+  info::device_type DeviceType;
+  backend Backend;
+  int32_t DeviceNum;
+};
+
+inline std::ostream &operator<<(std::ostream &Out, triple Trp) {
+  if (Trp.DeviceType == info::device_type::host) {
+    Out << std::string("host");
+  } else if (Trp.DeviceType == info::device_type::cpu) {
+    Out << std::string("cpu");
+  } else if (Trp.DeviceType == info::device_type::gpu) {
+    Out << std::string("gpu");
+  } else if (Trp.DeviceType == info::device_type::accelerator) {
+    Out << std::string("acceclerator");
+  } else if (Trp.DeviceType == info::device_type::all) {
+    Out << std::string("*");
+  }
+  Out << std::string(":");
+  switch (Trp.Backend) {
+  case backend::host:
+    Out << std::string("host");
+    break;
+  case backend::opencl:
+    Out << std::string("opencl");
+    break;
+  case backend::level_zero:
+    Out << std::string("level-zero");
+    break;
+  case backend::cuda:
+    Out << std::string("cuda");
+  }
+  if (Trp.DeviceNum != DEVICE_NUM_UNSPECIFIED) {
+    Out << std::string(":") << Trp.DeviceNum;
+  }
+  return Out;
+}
+
+} // namespace sycl
+} // __SYCL_INLINE_NAMESPACE(cl)

sycl/source/detail/config.def

@@ -15,3 +15,4 @@ CONFIG(SYCL_DISABLE_EXECUTION_GRAPH_CLEANUP, 1, __SYCL_DISABLE_EXECUTION_GRAPH_C
 CONFIG(SYCL_DEVICE_ALLOWLIST, 1024, __SYCL_DEVICE_ALLOWLIST)
 CONFIG(SYCL_BE, 16, __SYCL_BE)
 CONFIG(SYCL_PI_TRACE, 16, __SYCL_PI_TRACE)
+CONFIG(SYCL_DEVICE_TRIPLE, 1024, __SYCL_DEVICE_TRIPL)

sycl/source/detail/config.hpp

@@ -11,6 +11,8 @@
 #include <CL/sycl/backend_types.hpp>
 #include <CL/sycl/detail/defines.hpp>
 #include <CL/sycl/detail/pi.hpp>
+#include <CL/sycl/info/info_desc.hpp>
+#include <CL/sycl/triple.hpp>
 
 #include <algorithm>
 #include <array>
@@ -163,6 +165,118 @@ template <> class SYCLConfig<SYCL_PI_TRACE> {
   }
 };
 
+template <> class SYCLConfig<SYCL_DEVICE_TRIPLE> {
+  using BaseT = SYCLConfigBase<SYCL_DEVICE_TRIPLE>;
+
+public:
+  static std::vector<triple> *get() {
+    static bool Initialized = false;
+    static std::string String;
+    static std::vector<triple> TripleList;
+
+    // Configuration parameters are processed only once, like reading a string
+    // from environment and converting it into a typed object.
+    if (Initialized) {
+      if (TripleList.size()) {
+        return &TripleList;
+      } else {
+        return nullptr;
+      }
+    }
+
+    const std::array<std::pair<std::string, info::device_type>, 5>
+        SyclDeviceTypeMap = {{{"host", info::device_type::host},
+                              {"cpu", info::device_type::cpu},
+                              {"gpu", info::device_type::gpu},
+                              {"acc", info::device_type::accelerator},
+                              {"*", info::device_type::all}}};
+    const std::array<std::pair<std::string, backend>, 4> SyclBeMap = {
+        {{"opencl", backend::opencl},
+         {"level0", backend::level_zero},
+         {"level_zero", backend::level_zero},
+         {"cuda", backend::cuda}}};
+
+    Initialized = true;
+    const char *ValStr = BaseT::getRawValue();
+    if (ValStr) {
+      String = ValStr;
+      std::transform(String.begin(), String.end(), String.begin(), ::tolower);
+      bool MoreTriple = true;
+      size_t Pos = 0;
+      while (MoreTriple) {
+        MoreTriple = false;
+        triple Trp;
+        // device_type is required entry
+        auto It = std::find_if(
+            std::begin(SyclDeviceTypeMap), std::end(SyclDeviceTypeMap),
+            [=,
+             &Pos](const std::pair<std::string, info::device_type> &element) {
+              size_t Found = String.find(element.first, Pos);
+              if (Found != std::string::npos) {
+                Pos = Found;
+                return true;
+              }
+              return false;
+            });
+        if (It == SyclDeviceTypeMap.end())
+          pi::die("Invalid device_type. "
+                  "Valid values are host/cpu/gpu/acc/*");
+
+        // initialize optional entries with default values
+        if (It->second == info::device_type::gpu) {
+          Trp = {It->second, backend::level_zero, DEVICE_NUM_UNSPECIFIED};
+        } else {
+          Trp = {It->second, backend::opencl, DEVICE_NUM_UNSPECIFIED};
+        }
+
+        // update optional entries, backend
+        size_t ColonPos = String.find(":", Pos);
+        size_t CommaPos = String.find(",", Pos);
+
+        if (ColonPos != std::string::npos) {
+          Pos = ColonPos + 1;
+          if ((CommaPos != std::string::npos && ColonPos < CommaPos) ||
+              (CommaPos == std::string::npos)) {
+            auto It = std::find_if(
+                std::begin(SyclBeMap), std::end(SyclBeMap),
+                [=, &Pos](const std::pair<std::string, backend> &element) {
+                  size_t Found = String.find(element.first, Pos);
+                  if (Found != std::string::npos) {
+                    Pos = Found;
+                    return true;
+                  }
+                  return false;
+                });
+            if (It == SyclBeMap.end())
+              pi::die("Invalid backend. "
+                      "Valid values are opencl/level0/cuda");
+            Trp.Backend = It->second;
+          }
+
+          // update optional entry, device number
+          ColonPos = String.find(":", Pos);
+          if (ColonPos != std::string::npos) {
+            Pos = ColonPos + 1;
+            if ((CommaPos != std::string::npos && ColonPos < CommaPos) ||
+                (CommaPos == std::string::npos)) {
+              Trp.DeviceNum = atoi(String.c_str() + Pos);
+            }
+          }
+        }
+        TripleList.push_back(Trp);
+
+        if (CommaPos != std::string::npos) {
+          MoreTriple = true;
+          Pos = CommaPos + 1;
+        }
+      } // end of while
+    } else {
+      return nullptr;
+    }
+    return &TripleList;
+  }
+};
+
 } // namespace detail
 } // namespace sycl
 } // __SYCL_INLINE_NAMESPACE(cl)

sycl/source/detail/pi.cpp

@@ -214,9 +214,28 @@ bool findPlugins(vector_class<std::pair<std::string, backend>> &PluginNames) {
   // search is done for libpi_opencl.so/pi_opencl.dll file in LD_LIBRARY_PATH
   // env only.
   //
-  PluginNames.emplace_back(OPENCL_PLUGIN_NAME, backend::opencl);
-  PluginNames.emplace_back(LEVEL_ZERO_PLUGIN_NAME, backend::level_zero);
-  PluginNames.emplace_back(CUDA_PLUGIN_NAME, backend::cuda);
+  std::vector<triple> *Triples = SYCLConfig<SYCL_DEVICE_TRIPLE>::get();
+  bool OpenclFound = false;
+  bool LevelZeroFound = false;
+  bool CudaFound = false;
+  if (!Triples || Triples->size() == 0) {
+    PluginNames.emplace_back(OPENCL_PLUGIN_NAME, backend::opencl);
+    PluginNames.emplace_back(LEVEL_ZERO_PLUGIN_NAME, backend::level_zero);
+    PluginNames.emplace_back(CUDA_PLUGIN_NAME, backend::cuda);
+  } else {
+    for (triple Trp : *Triples) {
+      if (!OpenclFound && Trp.Backend == backend::opencl) {
+        PluginNames.emplace_back(OPENCL_PLUGIN_NAME, backend::opencl);
+        OpenclFound = true;
+      } else if (!LevelZeroFound && Trp.Backend == backend::level_zero) {
+        PluginNames.emplace_back(LEVEL_ZERO_PLUGIN_NAME, backend::level_zero);
+        LevelZeroFound = true;
+      } else if (!CudaFound && Trp.Backend == backend::cuda) {
+        PluginNames.emplace_back(CUDA_PLUGIN_NAME, backend::cuda);
+        CudaFound = true;
+      }
+    }
+  }
   return true;
 }
 

sycl/test/basic_tests/select_device.cpp

@@ -0,0 +1,71 @@
+// RUN: %clangxx -fsycl -fsycl-targets=%sycl_triple %s -o %t.out
+// RUN: %t.out
+// RUN: env SYCL_DEVICE_TRIPLE=cpu %t.out
+// RUN: env SYCL_DEVICE_TRIPLE=gpu:level0 %t.out
+// RUN: env SYCL_DEVICE_TRIPLE=gpu:opencl %t.out
+// RUN: env SYCL_DEVICE_TRIPLE=cpu,gpu:level0 %t.out
+//
+// Checks if only specified device types can be acquired from select_device
+// when SYCL_DEVICE_TRIPLE is set
+// Checks that no device is selected when no device of desired type is
+// available.
+// UNSUPPORTED: windows
+
+#include <CL/sycl.hpp>
+#include <iostream>
+
+using namespace cl::sycl;
+
+int main() {
+  const char *envVal = std::getenv("SYCL_DEVICE_TRIPLE");
+  std::string forcedPIs;
+  if (envVal) {
+    std::cout << "SYCL_DEVICE_TRIPLE=" << envVal << std::endl;
+    forcedPIs = envVal;
+  }
+  if (!envVal || forcedPIs.find("gpu:level0") != std::string::npos) {
+    default_selector ds;
+    device d = ds.select_device();
+    std::cout << "Level-zero GPU Device is found: " << std::boolalpha
+              << d.is_gpu() << std::endl;
+  }
+  if (!envVal || forcedPIs.find("gpu:opencl") != std::string::npos) {
+    gpu_selector gs;
+    device d = gs.select_device();
+    std::cout << "OpenCL GPU Device is found: " << std::boolalpha << d.is_gpu()
+              << std::endl;
+  }
+  if (!envVal || forcedPIs.find("cpu") != std::string::npos) {
+    cpu_selector cs;
+    device d = cs.select_device();
+    std::cout << "CPU device is found: " << d.is_cpu() << std::endl;
+  }
+  // HOST device is always available regardless of SYCL_DEVICE_TRIPLE
+  {
+    host_selector hs;
+    device d = hs.select_device();
+    std::cout << "HOST device is found: " << d.is_host() << std::endl;
+  }
+  if (!envVal || forcedPIs.find("accelerator") != std::string::npos) {
+    accelerator_selector as;
+    device d = as.select_device();
+    std::cout << "ACC device is found: " << d.is_accelerator() << std::endl;
+  }
+  if (envVal && (forcedPIs.find("cpu") == std::string::npos &&
+                 // remove the following condition when SYCL_DEVICE_TRIPLE
+                 // filter works in device selectors
+                 forcedPIs.find("opencl") == std::string::npos &&
+                 forcedPIs.find("*") == std::string::npos)) {
+    try {
+      cpu_selector cs;
+      device d = cs.select_device();
+    } catch (...) {
+      std::cout << "Expectedly, CPU device is not found." << std::endl;
+      return 0; // expected
+    }
+    std::cout << "Error: CPU device is found" << std::endl;
+    return -1;
+  }
+
+  return 0;
+}