[SYCL] Deprecate SYCL_DEVICE_FILTER environment variable (#7207)

- This patch prints an error warning when the environment variable
SYCL_DEVICE_FILTER is set.
- In-tree tests now use ONEAPI_DEVICE_SELECTOR instead of
SYCL_DEVICE_FILTER.
- The function SYCLConfig<SYCL_DEVICE_FILTER> which retrieves the value
of the deprecated environment variable is also deprecated.
- A switch is added to pi::findPlugins() to use ONEAPI_DEVICE_SELECTOR
if possible

Signed-off-by: Rauf, Rana <[email protected]>
Co-authored-by: Alexey Bader <[email protected]>

Author: raaiq1

sycl/doc/EnvironmentVariables.md

@@ -10,7 +10,7 @@ compiler and runtime.
 | `ONEAPI_DEVICE_SELECTOR` | [See below.](#oneapi_device_selector)  | This device selection environment variable can be used to limit the choice of devices available when the SYCL-using application is run.  Useful for limiting devices to a certain type (like GPUs or accelerators) or backends (like Level Zero or OpenCL).  This device selection mechanism is replacing `SYCL_DEVICE_FILTER` .  The `ONEAPI_DEVICE_SELECTOR` syntax is shared with OpenMP and also allows sub-devices to be chosen. [See below.](#oneapi_device_selector) for a full description.   |
 | `SYCL_BE` (deprecated) | `PI_OPENCL`, `PI_LEVEL_ZERO`, `PI_CUDA` | Force SYCL RT to consider only devices of the specified backend during the device selection.  The `SYCL_BE` environment variable is deprecated and will be removed soon. Please use the new env var `ONEAPI_DEVICE_SELECTOR` instead. |
 | `SYCL_DEVICE_TYPE` (deprecated) | 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 `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. The `SYCL_DEVICE_TYPE` environment variable is deprecated and will be removed soon. Please use the new env var `ONEAPI_DEVICE_SELECTOR` instead. |
-| `SYCL_DEVICE_FILTER` | `backend:device_type:device_num` | See Section [`SYCL_DEVICE_FILTER`](#sycl_device_filter)  below. |
+| `SYCL_DEVICE_FILTER` (deprecated) | `backend:device_type:device_num` | Please use `ONEAPI_DEVICE_SELECTOR` environment variable instead. See section [`SYCL_DEVICE_FILTER`](#sycl_device_filter) below for `SYCL_DEVICE_FILTER` description. |
 | `SYCL_DEVICE_ALLOWLIST` | See [below](#sycl_device_allowlist) | Filter out devices that do not match the pattern specified. `BackendName` accepts `host`, `opencl`, `level_zero` or `cuda`. `DeviceType` accepts `host`, `cpu`, `gpu` or `acc`. `DeviceVendorId` accepts uint32_t in hex form (`0xXYZW`). `DriverVersion`, `PlatformVersion`, `DeviceName` and `PlatformName` accept regular expression. Special characters, such as parenthesis, must be escaped. DPC++ runtime will select only those devices which satisfy provided values above and regex. More than one device can be specified using the piping symbol "\|".|
 | `SYCL_DISABLE_PARALLEL_FOR_RANGE_ROUNDING` | Any(\*) | Disables automatic rounding-up of `parallel_for` invocation ranges. |
 | `SYCL_CACHE_DIR` | Path | Path to persistent cache root directory. Default values are `%AppData%\libsycl_cache` for Windows and `$XDG_CACHE_HOME/libsycl_cache` on Linux, if `XDG_CACHE_HOME` is not set then `$HOME/.cache/libsycl_cache`. When none of the environment variables are set SYCL persistent cache is disabled. |

sycl/source/detail/config.hpp

@@ -307,7 +307,9 @@ template <> class SYCLConfig<ONEAPI_DEVICE_SELECTOR> {
 // ---------------------------------------
 // SYCL_DEVICE_FILTER support
 
-template <> class SYCLConfig<SYCL_DEVICE_FILTER> {
+template <>
+class __SYCL2020_DEPRECATED("Use SYCLConfig<ONEAPI_DEVICE_SELECTOR> instead")
+    SYCLConfig<SYCL_DEVICE_FILTER> {
   using BaseT = SYCLConfigBase<SYCL_DEVICE_FILTER>;
 
 public:
@@ -323,6 +325,14 @@ template <> class SYCLConfig<SYCL_DEVICE_FILTER> {
 
     const char *ValStr = BaseT::getRawValue();
     if (ValStr) {
+
+      std::cerr
+          << "\nWARNING: The enviroment variable SYCL_DEVICE_FITLER"
+             " is deprecated. Please use ONEAPI_DEVICE_SELECTOR instead.\n"
+             "For more details, please refer to:\n"
+             "https://github.com/intel/llvm/blob/sycl/sycl/doc/"
+             "EnvironmentVariables.md#oneapi_device_selector\n\n";
+
       FilterList = &GlobalHandler::instance().getDeviceFilterList(ValStr);
     }
 

sycl/source/detail/pi.cpp

@@ -276,14 +276,23 @@ std::vector<std::pair<std::string, backend>> findPlugins() {
   // search is done for libpi_opencl.so/pi_opencl.dll file in LD_LIBRARY_PATH
   // env only.
   //
+
   device_filter_list *FilterList = SYCLConfig<SYCL_DEVICE_FILTER>::get();
-  if (!FilterList) {
+  ods_target_list *OdsTargetList = SYCLConfig<ONEAPI_DEVICE_SELECTOR>::get();
+
+  // Will we be filtering with SYCL_DEVICE_FILTER or ONEAPI_DEVICE_SELECTOR ?
+  // We do NOT attempt to support both simultaneously.
+  if (OdsTargetList && FilterList) {
+    throw sycl::exception(sycl::make_error_code(errc::invalid),
+                          "ONEAPI_DEVICE_SELECTOR cannot be used in "
+                          "conjunction with SYCL_DEVICE_FILTER");
+  } else if (!FilterList && !OdsTargetList) {
     PluginNames.emplace_back(__SYCL_OPENCL_PLUGIN_NAME, backend::opencl);
     PluginNames.emplace_back(__SYCL_LEVEL_ZERO_PLUGIN_NAME,
                              backend::ext_oneapi_level_zero);
     PluginNames.emplace_back(__SYCL_CUDA_PLUGIN_NAME, backend::ext_oneapi_cuda);
     PluginNames.emplace_back(__SYCL_HIP_PLUGIN_NAME, backend::ext_oneapi_hip);
-  } else {
+  } else if (FilterList) {
     std::vector<device_filter> Filters = FilterList->get();
     bool OpenCLFound = false;
     bool LevelZeroFound = false;
@@ -321,6 +330,26 @@ std::vector<std::pair<std::string, backend>> findPlugins() {
         HIPFound = true;
       }
     }
+  } else {
+    ods_target_list &list = *OdsTargetList;
+    if (list.backendCompatible(backend::opencl)) {
+      PluginNames.emplace_back(__SYCL_OPENCL_PLUGIN_NAME, backend::opencl);
+    }
+    if (list.backendCompatible(backend::ext_oneapi_level_zero)) {
+      PluginNames.emplace_back(__SYCL_LEVEL_ZERO_PLUGIN_NAME,
+                               backend::ext_oneapi_level_zero);
+    }
+    if (list.backendCompatible(backend::ext_oneapi_cuda)) {
+      PluginNames.emplace_back(__SYCL_CUDA_PLUGIN_NAME,
+                               backend::ext_oneapi_cuda);
+    }
+    if (list.backendCompatible(backend::ext_intel_esimd_emulator)) {
+      PluginNames.emplace_back(__SYCL_ESIMD_EMULATOR_PLUGIN_NAME,
+                               backend::ext_intel_esimd_emulator);
+    }
+    if (list.backendCompatible(backend::ext_oneapi_hip)) {
+      PluginNames.emplace_back(__SYCL_HIP_PLUGIN_NAME, backend::ext_oneapi_hip);
+    }
   }
   return PluginNames;
 }

sycl/test/Unit/lit.cfg.py

@@ -76,7 +76,7 @@ def find_shlibpath_var():
 # The mock plugin currently appears as an opencl plugin, but could be changed in
 # the future. To avoid it being filtered out we set the filter to use the *
 # wildcard.
-config.environment['SYCL_DEVICE_FILTER'] = "*"
+config.environment['ONEAPI_DEVICE_SELECTOR'] = "'*:*'"
 lit_config.note("Using Mock Plugin.")
 
 config.environment['SYCL_CACHE_DIR'] = config.llvm_obj_root + "/sycl_cache"

sycl/unittests/Extensions/FPGADeviceSelectors.cpp

@@ -66,6 +66,20 @@ static pi_result redefinedDeviceGetInfo(pi_device device,
       *param_value_size_ret = sizeof(MockDeviceName);
     return PI_SUCCESS;
   }
+  // Mock FPGA has no sub-devices
+  case PI_DEVICE_INFO_PARTITION_PROPERTIES: {
+    if (param_value_size_ret) {
+      *param_value_size_ret = 0;
+    }
+    return PI_SUCCESS;
+  }
+  case PI_DEVICE_INFO_PARTITION_AFFINITY_DOMAIN: {
+    assert(param_value_size == sizeof(pi_device_affinity_domain));
+    if (param_value) {
+      *static_cast<pi_device_affinity_domain *>(param_value) = 0;
+    }
+    return PI_SUCCESS;
+  }
   default:
     return PI_SUCCESS;
   }

sycl/unittests/buffer/BufferLocation.cpp

@@ -66,6 +66,18 @@ static pi_result redefinedDeviceGetInfo(pi_device device,
       strcpy(dst, name.data());
     }
   }
+  // This mock device has no sub-devices
+  if (param_name == PI_DEVICE_INFO_PARTITION_PROPERTIES) {
+    if (param_value_size_ret) {
+      *param_value_size_ret = 0;
+    }
+  }
+  if (param_name == PI_DEVICE_INFO_PARTITION_AFFINITY_DOMAIN) {
+    assert(param_value_size == sizeof(pi_device_affinity_domain));
+    if (param_value) {
+      *static_cast<pi_device_affinity_domain *>(param_value) = 0;
+    }
+  }
   return PI_SUCCESS;
 }
 

sycl/unittests/helpers/PiMockPlugin.hpp

@@ -154,6 +154,20 @@ inline pi_result mock_piDeviceGetInfo(pi_device device,
       *param_value_size_ret = sizeof(PI_TRUE);
     return PI_SUCCESS;
   }
+  // This mock GPU device has no sub-devices
+  case PI_DEVICE_INFO_PARTITION_PROPERTIES: {
+    if (param_value_size_ret) {
+      *param_value_size_ret = 0;
+    }
+    return PI_SUCCESS;
+  }
+  case PI_DEVICE_INFO_PARTITION_AFFINITY_DOMAIN: {
+    assert(param_value_size == sizeof(pi_device_affinity_domain));
+    if (param_value) {
+      *static_cast<pi_device_affinity_domain *>(param_value) = 0;
+    }
+    return PI_SUCCESS;
+  }
   default:
     return PI_SUCCESS;
   }

sycl/unittests/kernel-and-program/DeviceInfo.cpp

@@ -45,6 +45,19 @@ static pi_result redefinedDeviceGetInfo(pi_device device,
     TestContext->FreeMemoryInfoCalled = true;
   }
 
+  // This mock device has no sub-devices
+  if (param_name == PI_DEVICE_INFO_PARTITION_PROPERTIES) {
+    if (param_value_size_ret) {
+      *param_value_size_ret = 0;
+    }
+  }
+  if (param_name == PI_DEVICE_INFO_PARTITION_AFFINITY_DOMAIN) {
+    assert(param_value_size == sizeof(pi_device_affinity_domain));
+    if (param_value) {
+      *static_cast<pi_device_affinity_domain *>(param_value) = 0;
+    }
+  }
+
   return PI_SUCCESS;
 }
 

sycl/unittests/kernel-and-program/MultipleDevsCache.cpp

@@ -64,6 +64,19 @@ static pi_result redefinedDeviceGetInfo(pi_device device,
     auto *Result = reinterpret_cast<pi_bool *>(param_value);
     *Result = true;
   }
+
+  // This mock device has no sub-devices
+  if (param_name == PI_DEVICE_INFO_PARTITION_PROPERTIES) {
+    if (param_value_size_ret) {
+      *param_value_size_ret = 0;
+    }
+  }
+  if (param_name == PI_DEVICE_INFO_PARTITION_AFFINITY_DOMAIN) {
+    assert(param_value_size == sizeof(pi_device_affinity_domain));
+    if (param_value) {
+      *static_cast<pi_device_affinity_domain *>(param_value) = 0;
+    }
+  }
   return PI_SUCCESS;
 }
 

sycl/unittests/scheduler/AllocaLinking.cpp

@@ -28,6 +28,19 @@ static pi_result redefinedDeviceGetInfo(pi_device Device,
     auto *Result = reinterpret_cast<_pi_device_type *>(ParamValue);
     *Result = PI_DEVICE_TYPE_CPU;
   }
+
+  // This mock device has no sub-devices
+  if (ParamName == PI_DEVICE_INFO_PARTITION_PROPERTIES) {
+    if (ParamValueSizeRet) {
+      *ParamValueSizeRet = 0;
+    }
+  }
+  if (ParamName == PI_DEVICE_INFO_PARTITION_AFFINITY_DOMAIN) {
+    assert(ParamValueSize == sizeof(pi_device_affinity_domain));
+    if (ParamValue) {
+      *static_cast<pi_device_affinity_domain *>(ParamValue) = 0;
+    }
+  }
   return PI_SUCCESS;
 }
 

sycl/unittests/scheduler/NoHostUnifiedMemory.cpp

@@ -29,6 +29,19 @@ static pi_result redefinedDeviceGetInfo(pi_device Device,
     auto *Result = reinterpret_cast<_pi_device_type *>(ParamValue);
     *Result = PI_DEVICE_TYPE_CPU;
   }
+
+  // This mock device has no sub-devices
+  if (ParamName == PI_DEVICE_INFO_PARTITION_PROPERTIES) {
+    if (ParamValueSizeRet) {
+      *ParamValueSizeRet = 0;
+    }
+  }
+  if (ParamName == PI_DEVICE_INFO_PARTITION_AFFINITY_DOMAIN) {
+    assert(ParamValueSize == sizeof(pi_device_affinity_domain));
+    if (ParamValue) {
+      *static_cast<pi_device_affinity_domain *>(ParamValue) = 0;
+    }
+  }
   return PI_SUCCESS;
 }