[SYCL] Implement new env var SYCL_DEVICE_FILTER

sycl/doc/EnvironmentVariables.md

@@ -14,6 +14,7 @@ subject to change. Do not rely on these variables in production code.
 | 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_DEVICE_FILTER (name TBD) | {backend:device_type: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 by a default_selector, a heuristic will choose the device that has the closest match. HOST device is always available for the default_selecotr and the filter won't affect HOST device availability in any case. Possible values of device_type are \*,host,cpu,gpu,acc. Possible values of backend are \*,opencl, level_zero, cuda. Device_num is an unsigned integer that indexes the enumeration of devices from sycl::platform::get_device() call. All triple entries are optional, but one of them should be present. For example, to use cpu and level_zero gpu device number 0, one can set SYCL_DEVICE_FILTER=cpu,level_zero:gpu::0. This environment variable will limit loading only specified plugins into the SYCL RT. For example, SYCL_DEVICE_FILTER=level_zero and cpu_selector will throw an error because the CPU device is not supported by the level_zero backend. |
 | SYCL_PROGRAM_COMPILE_OPTIONS | String of valid OpenCL compile options | Override compile options for all programs. |
 | SYCL_PROGRAM_LINK_OPTIONS | String of valid OpenCL link options | Override link options for all programs. |
 | SYCL_USE_KERNEL_SPV | Path to the SPIR-V binary | Load device image from the specified file. If runtime is unable to read the file, `cl::sycl::runtime_error` exception is thrown.|

sycl/include/CL/sycl/backend_types.hpp

@@ -18,7 +18,7 @@
 __SYCL_INLINE_NAMESPACE(cl) {
 namespace sycl {
 
-enum class backend : char { host, opencl, level_zero, cuda };
+enum class backend : char { host, opencl, level_zero, cuda, all };
 
 template <backend name, typename SYCLObjectT> struct interop;
 
@@ -35,6 +35,9 @@ inline std::ostream &operator<<(std::ostream &Out, backend be) {
     break;
   case backend::cuda:
     Out << std::string("cuda");
+    break;
+  case backend::all:
+    Out << std::string("all");
   }
   return Out;
 }

sycl/include/CL/sycl/detail/device_filter.hpp

@@ -0,0 +1,96 @@
+//==---------- device_filter.hpp - SYCL device filter descriptor -----------==//
+//
+// 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 <iostream>
+#include <string>
+
+__SYCL_INLINE_NAMESPACE(cl) {
+namespace sycl {
+namespace detail {
+
+struct device_filter {
+  backend Backend = backend::host;
+  info::device_type DeviceType = info::device_type::all;
+  int DeviceNum = 0;
+  bool HasBackend = false;
+  bool HasDeviceType = false;
+  bool HasDeviceNum = false;
+  int MatchesSeen = 0;
+
+  device_filter(){};
+  device_filter(std::string &FilterString);
+  friend std::ostream &operator<<(std::ostream &Out,
+                                  const device_filter &Filter);
+};
+
+class device_filter_list {
+  std::vector<device_filter> FilterList;
+
+public:
+  device_filter_list() {}
+  device_filter_list(std::string &FilterString);
+  device_filter_list(device_filter &Filter);
+  std::vector<device_filter> &get() { return FilterList; }
+  friend std::ostream &operator<<(std::ostream &Out,
+                                  const device_filter_list &List);
+};
+
+inline std::ostream &operator<<(std::ostream &Out,
+                                const device_filter &Filter) {
+  switch (Filter.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");
+    break;
+  case backend::all:
+    Out << std::string("*");
+  }
+  Out << std::string(":");
+  if (Filter.DeviceType == info::device_type::host) {
+    Out << std::string("host");
+  } else if (Filter.DeviceType == info::device_type::cpu) {
+    Out << std::string("cpu");
+  } else if (Filter.DeviceType == info::device_type::gpu) {
+    Out << std::string("gpu");
+  } else if (Filter.DeviceType == info::device_type::accelerator) {
+    Out << std::string("acceclerator");
+  } else if (Filter.DeviceType == info::device_type::all) {
+    Out << std::string("*");
+  }
+  if (Filter.HasDeviceNum) {
+    Out << std::string(":") << Filter.DeviceNum;
+  }
+  return Out;
+}
+
+inline std::ostream &operator<<(std::ostream &Out,
+                                const device_filter_list &List) {
+  for (const device_filter &Filter : List.FilterList) {
+    Out << Filter;
+    Out << ",";
+  }
+  return Out;
+}
+
+} // namespace detail
+} // namespace sycl
+} // __SYCL_INLINE_NAMESPACE(cl)

sycl/source/CMakeLists.txt

@@ -108,6 +108,7 @@ set(SYCL_SOURCES
     "detail/config.cpp"
     "detail/context_impl.cpp"
     "detail/device_binary_image.cpp"
+    "detail/device_filter.cpp"
     "detail/device_impl.cpp"
     "detail/error_handling/enqueue_kernel.cpp"
     "detail/event_impl.cpp"

sycl/source/detail/config.def

@@ -16,3 +16,4 @@ CONFIG(SYCL_DEVICE_ALLOWLIST, 1024, __SYCL_DEVICE_ALLOWLIST)
 CONFIG(SYCL_BE, 16, __SYCL_BE)
 CONFIG(SYCL_PI_TRACE, 16, __SYCL_PI_TRACE)
 CONFIG(SYCL_DEVICELIB_NO_FALLBACK, 1, __SYCL_DEVICELIB_NO_FALLBACK)
+CONFIG(SYCL_DEVICE_FILTER, 1024, __SYCL_DEVICE_FILTER)

sycl/source/detail/config.hpp

@@ -10,7 +10,9 @@
 
 #include <CL/sycl/backend_types.hpp>
 #include <CL/sycl/detail/defines.hpp>
+#include <CL/sycl/detail/device_filter.hpp>
 #include <CL/sycl/detail/pi.hpp>
+#include <CL/sycl/info/info_desc.hpp>
 
 #include <algorithm>
 #include <array>
@@ -163,6 +165,36 @@ template <> class SYCLConfig<SYCL_PI_TRACE> {
   }
 };
 
+template <> class SYCLConfig<SYCL_DEVICE_FILTER> {
+  using BaseT = SYCLConfigBase<SYCL_DEVICE_FILTER>;
+
+public:
+  static device_filter_list *get() {
+    static bool Initialized = false;
+    static device_filter_list *FilterList = nullptr;
+
+    // Configuration parameters are processed only once, like reading a string
+    // from environment and converting it into a typed object.
+    if (Initialized) {
+      return FilterList;
+    }
+
+    const char *ValStr = BaseT::getRawValue();
+    if (ValStr) {
+      std::string FilterString = ValStr;
+      static device_filter_list DFL = FilterString;
+      FilterList = &DFL;
+    }
+    // as mentioned above, configuration parameters are process only once.
+    // If multiple threads are checking this env var at the same time,
+    // they will end up setting the configration to the same value.
+    // If other threads check after one thread already set configration,
+    // the threads will get the same value as the first thread.
+    Initialized = true;
+    return FilterList;
+  }
+};
+
 } // namespace detail
 } // namespace sycl
 } // __SYCL_INLINE_NAMESPACE(cl)

sycl/source/detail/device_filter.cpp

@@ -0,0 +1,116 @@
+//==------------------- device_filter.cpp ----------------------------------==//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#include <CL/sycl/detail/device_filter.hpp>
+#include <CL/sycl/info/info_desc.hpp>
+#include <detail/config.hpp>
+#include <detail/device_impl.hpp>
+
+#include <cstring>
+
+__SYCL_INLINE_NAMESPACE(cl) {
+namespace sycl {
+namespace detail {
+
+device_filter::device_filter(std::string &FilterString) {
+  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},
+       {"level_zero", backend::level_zero},
+       {"cuda", backend::cuda},
+       {"*", backend::all}}};
+
+  // handle the optional 1st entry, backend
+  size_t Cursor = 0;
+  size_t ColonPos = FilterString.find(":", Cursor);
+  auto It = std::find_if(
+      std::begin(SyclBeMap), std::end(SyclBeMap),
+      [=, &Cursor](const std::pair<std::string, backend> &Element) {
+        size_t Found = FilterString.find(Element.first, Cursor);
+        if (Found != std::string::npos) {
+          Cursor = Found;
+          return true;
+        }
+        return false;
+      });
+  if (It == SyclBeMap.end()) {
+    Backend = backend::all;
+  } else {
+    Backend = It->second;
+    if (ColonPos != std::string::npos) {
+      Cursor = ColonPos + 1;
+    } else {
+      Cursor = Cursor + It->first.size();
+    }
+  }
+
+  // handle the optional 2nd entry, device type
+  auto Iter = std::find_if(
+      std::begin(SyclDeviceTypeMap), std::end(SyclDeviceTypeMap),
+      [=, &Cursor](const std::pair<std::string, info::device_type> &Element) {
+        size_t Found = FilterString.find(Element.first, Cursor);
+        if (Found != std::string::npos) {
+          Cursor = Found;
+          return true;
+        }
+        return false;
+      });
+  if (Iter == SyclDeviceTypeMap.end()) {
+    DeviceType = info::device_type::all;
+  } else {
+    DeviceType = Iter->second;
+    ColonPos = FilterString.find(":", Cursor);
+    if (ColonPos != std::string::npos) {
+      Cursor = ColonPos + 1;
+    } else {
+      Cursor = Cursor + Iter->first.size();
+    }
+  }
+
+  // handle the optional 3rd entry, device number
+  if (Cursor < FilterString.size()) {
+    try {
+      DeviceNum = stoi(FilterString.substr(ColonPos + 1));
+      HasDeviceNum = true;
+    } catch (...) {
+      char message[100];
+      strcpy(message, "Invalid device filter: ");
+      std::strcat(message, FilterString.c_str());
+      std::strcat(message,
+                  "\nPossible backend values are {opencl,level_zero,cuda,*}.");
+      std::strcat(message, "\nPossible device types are {host,cpu,gpu,acc,*}.");
+      std::strcat(message,
+                  "\nDevice number should be an non-negative integer.\n");
+      throw cl::sycl::invalid_parameter_error(message, PI_INVALID_VALUE);
+    }
+  }
+}
+
+device_filter_list::device_filter_list(std::string &FilterString) {
+  std::transform(FilterString.begin(), FilterString.end(), FilterString.begin(),
+                 ::tolower);
+  size_t Pos = 0;
+  while (Pos < FilterString.size()) {
+    size_t CommaPos = FilterString.find(",", Pos);
+    if (CommaPos == std::string::npos) {
+      CommaPos = FilterString.size();
+    }
+    std::string SubString = FilterString.substr(Pos, CommaPos - Pos);
+    FilterList.push_back(device_filter(SubString));
+    Pos = CommaPos + 1;
+  }
+}
+
+} // namespace detail
+} // namespace sycl
+} // __SYCL_INLINE_NAMESPACE(cl)

sycl/source/detail/filter_selector_impl.cpp

@@ -62,13 +62,13 @@ filter create_filter(const std::string &Input) {
 
   for (const std::string &Token : Tokens) {
     if (Token == "cpu" && !Result.HasDeviceType) {
-      Result.DeviceType = PI_DEVICE_TYPE_CPU;
+      Result.DeviceType = info::device_type::cpu;
       Result.HasDeviceType = true;
     } else if (Token == "gpu" && !Result.HasDeviceType) {
-      Result.DeviceType = PI_DEVICE_TYPE_GPU;
+      Result.DeviceType = info::device_type::gpu;
       Result.HasDeviceType = true;
     } else if (Token == "accelerator" && !Result.HasDeviceType) {
-      Result.DeviceType = PI_DEVICE_TYPE_ACC;
+      Result.DeviceType = info::device_type::accelerator;
       Result.HasDeviceType = true;
     } else if (Token == "opencl" && !Result.HasBackend) {
       Result.Backend = backend::opencl;
@@ -134,8 +134,7 @@ int filter_selector_impl::operator()(const device &Dev) const {
       BackendOK = (BE == Filter.Backend);
     }
     if (Filter.HasDeviceType) {
-      RT::PiDeviceType DT =
-          sycl::detail::getSyclObjImpl(Dev)->get_device_type();
+      info::device_type DT = Dev.get_info<info::device::device_type>();
       DeviceTypeOK = (DT == Filter.DeviceType);
     }
     if (Filter.HasDeviceNum) {

sycl/source/detail/filter_selector_impl.hpp

@@ -8,6 +8,7 @@
 
 #pragma once
 
+#include <CL/sycl/detail/device_filter.hpp>
 #include <CL/sycl/device_selector.hpp>
 
 #include <vector>
@@ -21,15 +22,7 @@ class device;
 namespace ONEAPI {
 namespace detail {
 
-struct filter {
-  backend Backend = backend::host;
-  RT::PiDeviceType DeviceType = PI_DEVICE_TYPE_ALL;
-  int DeviceNum = 0;
-  bool HasBackend = false;
-  bool HasDeviceType = false;
-  bool HasDeviceNum = false;
-  int MatchesSeen = 0;
-};
+typedef struct sycl::detail::device_filter filter;
 
 class filter_selector_impl {
 public:

sycl/source/detail/pi.cpp

@@ -14,6 +14,7 @@
 #include "context_impl.hpp"
 #include <CL/sycl/context.hpp>
 #include <CL/sycl/detail/common.hpp>
+#include <CL/sycl/detail/device_filter.hpp>
 #include <CL/sycl/detail/pi.hpp>
 #include <detail/config.hpp>
 #include <detail/plugin.hpp>
@@ -214,9 +215,33 @@ 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);
+  device_filter_list *FilterList = SYCLConfig<SYCL_DEVICE_FILTER>::get();
+  if (!FilterList) {
+    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 {
+    std::vector<device_filter> Filters = FilterList->get();
+    bool OpenCLFound = false;
+    bool LevelZeroFound = false;
+    bool CudaFound = false;
+    for (const device_filter &Filter : Filters) {
+      backend Backend = Filter.Backend;
+      if (!OpenCLFound &&
+          (Backend == backend::opencl || Backend == backend::all)) {
+        PluginNames.emplace_back(OPENCL_PLUGIN_NAME, backend::opencl);
+        OpenCLFound = true;
+      } else if (!LevelZeroFound &&
+                 (Backend == backend::level_zero || Backend == backend::all)) {
+        PluginNames.emplace_back(LEVEL_ZERO_PLUGIN_NAME, backend::level_zero);
+        LevelZeroFound = true;
+      } else if (!CudaFound &&
+                 (Backend == backend::cuda || Backend == backend::all)) {
+        PluginNames.emplace_back(CUDA_PLUGIN_NAME, backend::cuda);
+        CudaFound = true;
+      }
+    }
+  }
   return true;
 }