[SYCL] Remove SYCL_DEVICE_FILTER support (#12384)

**Overview**
This PR removes support for SYCL_DEVICE_FILTER, and refactors
`Basic/diagnostics/device-check.cpp` to use ONEAPI_DEVICE_FILTER instead
of SYCL_DEVICE_TYPE, as the latter is depreciated.

Author: uditagarwal97

sycl/doc/EnvironmentVariables.md

@@ -8,7 +8,6 @@ compiler and runtime.
 | Environment variable | Values | Description |
 | -------------------- | ------ | ----------- |
 | `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_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`, `native_cpu` 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. |
@@ -110,32 +109,6 @@ A list of devices and their driver version following the pattern:
 Also may contain `PlatformVersion`, `DeviceName` and `PlatformName`. There is no
 fixed order of properties in the pattern.
 
-### `SYCL_DEVICE_FILTER`
-
-This environment variable limits the SYCL RT to use only a subset of the system's devices. Setting this environment variable affects all of the device query functions (`platform::get_devices()` and `platform::get_platforms()`) and all of the device selectors.
-
-The value of this environment variable is a comma separated list of filters, where each filter is a triple of the form "`backend`:`device_type`:`device_num`" (without the quotes). Each element of the triple is optional, but each filter must have at least one value. Possible values of `backend` are:
-- `host` (Deprecated)
-- `level_zero`
-- `opencl`
-- `cuda`
-- `hip`
-- `esimd_emulator` (Deprecated)
-- `*`
-
-Possible values of `device_type` are:
-- `host` (Deprecated)
-- `cpu`
-- `gpu`
-- `acc`
-- `*`
-
-`device_num` is an integer that indexes the enumeration of devices from the sycl-ls utility tool, where the first device in that enumeration has index zero in each backend. For example, `SYCL_DEVICE_FILTER=2` will return all devices with index '2' from all different backends. If multiple devices satisfy this device number (e.g., GPU and CPU devices can be assigned device number '2'), then default_selector will choose the device with the highest heuristic point.  When `SYCL_DEVICE_ALLOWLIST` is set, it is applied before enumerating devices and affects `device_num` values.
-
-Assuming a filter has all three elements of the triple, it selects only those devices that come from the given backend, have the specified device type, AND have the given device index. If more than one filter is specified, the RT is restricted to the union of devices selected by all filters.
-
-Note that all device selectors will throw an exception if the filtered list of devices does not include a device that satisfies the selector. For instance, `SYCL_DEVICE_FILTER=cpu` will cause `gpu_selector()` to throw an exception. `SYCL_DEVICE_FILTER` also limits loading only specified plugins into the SYCL RT. In particular, `SYCL_DEVICE_FILTER=level_zero` will cause the `cpu_selector` to throw an exception since SYCL RT will only load the `level_zero` backend which does not support any CPU devices at this time. When multiple devices satisfy the filter (e..g, `SYCL_DEVICE_FILTER=gpu`), only one of them will be selected.
-
 ## `SYCL_REDUCTION_PREFERRED_WORKGROUP_SIZE`
 
 This environment variable controls the preferred work-group size for reductions on specified device types. Setting this will affect all reductions without an explicitly specified work-group size on devices of types in the value of the environment variable.

sycl/doc/MultiTileCardWithLevelZero.md

@@ -19,9 +19,9 @@ by SYCL runtime. Thus in the example above there is CPU (managed by OpenCL backe
 GPUs corresponding to the single physical GPU (managed by either OpenCL or Level-Zero backend).
 There are few ways to filter observable root-devices.
 
-One is using environment variable SYCL_DEVICE_FILTER described in [EnvironmentVariables.md](https://github.com/intel/llvm/blob/sycl/sycl/doc/EnvironmentVariables.md)
+One is using environment variable ONEAPI_DEVICE_SELECTOR described in [EnvironmentVariables.md](https://github.com/intel/llvm/blob/sycl/sycl/doc/EnvironmentVariables.md)
 ```
-$ SYCL_DEVICE_FILTER=level_zero sycl-ls
+$ ONEAPI_DEVICE_SELECTOR=level_zero:* sycl-ls
 [level_zero:0] GPU : Intel(R) Level-Zero 1.1 [1.1.19792]
 ```
 Another way is to use similar SYCL API described in [sycl\_ext\_oneapi\_filter\_selector](extensions/supported/sycl_ext_oneapi_filter_selector.asciidoc)
@@ -33,7 +33,7 @@ On Windows these would appear as root-devices of multiple different SYCL platfor
 
 `CreateMultipleRootDevices=N NEOReadDebugKeys=1` evironment variables can be used to emulate multiple GPU cards, e.g.
 ```
-$ CreateMultipleRootDevices=2 NEOReadDebugKeys=1 SYCL_DEVICE_FILTER=level_zero sycl-ls
+$ CreateMultipleRootDevices=2 NEOReadDebugKeys=1 ONEAPI_DEVICE_SELECTOR=level_zero:* sycl-ls
 [level_zero:0] GPU : Intel(R) Level-Zero 1.1 [1.1.19792]
 [level_zero:1] GPU : Intel(R) Level-Zero 1.1 [1.1.19792]
 ```

sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md

@@ -52,7 +52,7 @@ For further details see here: <https://github.com/intel/llvm/blob/sycl/sycl/doc/
         
 There is an extension that introduces a filtering device selection to SYCL described in
 [sycl\_ext\_oneapi\_filter\_selector](../supported/sycl_ext_oneapi_filter_selector.asciidoc).
-Similar to how SYCL_DEVICE_FILTER or ONEAPI_DEVICE_SELECTOR applies filtering to the entire process this device selector can be used to
+Similar to how ONEAPI_DEVICE_SELECTOR applies filtering to the entire process this device selector can be used to
 programmatically select the Level-Zero backend.
                 
 When neither the environment variable nor the filtering device selector are used, the implementation chooses

sycl/doc/extensions/supported/sycl_ext_oneapi_srgb.asciidoc

@@ -130,7 +130,7 @@ And to run, be sure to select the OpenCL backend (works on both CPU and GPU devi
 
 [source]
 ----
-$ SYCL_DEVICE_FILTER=opencl:gpu ./myapp.bin
+$ ONEAPI_DEVICE_SELECTOR=opencl:gpu ./myapp.bin
 ----
 
 

sycl/include/sycl/detail/device_filter.hpp

@@ -46,6 +46,9 @@ struct ods_target {
   std::optional<unsigned> SubSubDeviceNum;
 
   bool IsNegativeTarget = false; // used to represent negative filters.
+  // used in filter selector to keep count of the number of devices with
+  // the same Backend and DeviceType.
+  int MatchesSeen = 0;
 
   ods_target(backend be) { Backend = be; };
   ods_target(){};
@@ -66,6 +69,7 @@ class ods_target_list {
 std::ostream &operator<<(std::ostream &Out, const ods_target &Target);
 std::vector<ods_target> Parse_ONEAPI_DEVICE_SELECTOR(const std::string &envStr);
 
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
 // ---------------------------------------
 // SYCL_DEVICE_FILTER support
 
@@ -127,6 +131,7 @@ inline std::ostream &operator<<(std::ostream &Out,
   }
   return Out;
 }
+#endif // __INTEL_PREVIEW_BREAKING_CHANGES
 
 } // namespace detail
 } // namespace _V1

sycl/source/detail/config.cpp

@@ -161,8 +161,9 @@ void dumpConfig() {
 #undef CONFIG
 }
 
-// Array is used by SYCL_DEVICE_FILTER and SYCL_DEVICE_ALLOWLIST and
-// ONEAPI_DEVICE_SELECTOR
+// Array is used by SYCL_DEVICE_ALLOWLIST and ONEAPI_DEVICE_SELECTOR.
+// TODO: host device type will be removed once sycl_ext_oneapi_filter_selector
+// is removed.
 const std::array<std::pair<std::string, info::device_type>, 6> &
 getSyclDeviceTypeMap() {
   static const std::array<std::pair<std::string, info::device_type>, 6>
@@ -178,6 +179,8 @@ getSyclDeviceTypeMap() {
 // Array is used by SYCL_DEVICE_FILTER and SYCL_DEVICE_ALLOWLIST and
 // ONEAPI_DEVICE_SELECTOR
 // TODO: Remove esimd_emulator in the next ABI breaking window.
+// TODO: host device type will be removed once sycl_ext_oneapi_filter_selector
+// is removed.
 const std::array<std::pair<std::string, backend>, 8> &getSyclBeMap() {
   static const std::array<std::pair<std::string, backend>, 8> SyclBeMap = {
       {{"host", backend::host},

sycl/source/detail/config.def

@@ -19,7 +19,9 @@ CONFIG(SYCL_PARALLEL_FOR_RANGE_ROUNDING_TRACE, 16, __SYCL_PARALLEL_FOR_RANGE_ROU
 CONFIG(SYCL_DISABLE_PARALLEL_FOR_RANGE_ROUNDING, 16, __SYCL_DISABLE_PARALLEL_FOR_RANGE_ROUNDING)
 CONFIG(SYCL_PARALLEL_FOR_RANGE_ROUNDING_PARAMS, 64, __SYCL_PARALLEL_FOR_RANGE_ROUNDING_PARAMS)
 CONFIG(SYCL_DEVICELIB_NO_FALLBACK, 1, __SYCL_DEVICELIB_NO_FALLBACK)
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
 CONFIG(SYCL_DEVICE_FILTER, 1024, __SYCL_DEVICE_FILTER)
+#endif
 CONFIG(SYCL_PROGRAM_LINK_OPTIONS, 64, __SYCL_PROGRAM_LINK_OPTIONS)
 CONFIG(SYCL_PROGRAM_COMPILE_OPTIONS, 64, __SYCL_PROGRAM_COMPILE_OPTIONS)
 CONFIG(SYCL_PROGRAM_APPEND_LINK_OPTIONS, 64, __SYCL_PROGRAM_APPEND_LINK_OPTIONS)

sycl/source/detail/config.hpp

@@ -231,8 +231,7 @@ template <> class SYCLConfig<SYCL_PARALLEL_FOR_RANGE_ROUNDING_PARAMS> {
   }
 };
 
-// Array is used by SYCL_DEVICE_FILTER and SYCL_DEVICE_ALLOWLIST and
-// ONEAPI_DEVICE_SELECTOR
+// Array is used by SYCL_DEVICE_ALLOWLIST and ONEAPI_DEVICE_SELECTOR.
 const std::array<std::pair<std::string, info::device_type>, 6> &
 getSyclDeviceTypeMap();
 
@@ -265,6 +264,7 @@ template <> class SYCLConfig<ONEAPI_DEVICE_SELECTOR> {
   }
 };
 
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
 // ---------------------------------------
 // SYCL_DEVICE_FILTER support
 
@@ -306,6 +306,7 @@ class __SYCL2020_DEPRECATED("Use SYCLConfig<ONEAPI_DEVICE_SELECTOR> instead")
     return FilterList;
   }
 };
+#endif // __INTEL_PREVIEW_BREAKING_CHANGES
 
 template <> class SYCLConfig<SYCL_ENABLE_DEFAULT_CONTEXTS> {
   using BaseT = SYCLConfigBase<SYCL_ENABLE_DEFAULT_CONTEXTS>;

sycl/source/detail/device_filter.cpp

@@ -288,7 +288,7 @@ ods_target_list::ods_target_list(const std::string &envStr) {
   TargetList = Parse_ONEAPI_DEVICE_SELECTOR(envStr);
 }
 
-// Backend is compatible with the SYCL_DEVICE_FILTER in the following cases.
+// Backend is compatible with the ONEAPI_DEVICE_SELECTOR in the following cases.
 // 1. Filter backend is '*' which means ANY backend.
 // 2. Filter backend match exactly with the given 'Backend'
 bool ods_target_list::backendCompatible(backend Backend) {
@@ -300,6 +300,7 @@ bool ods_target_list::backendCompatible(backend Backend) {
       });
 }
 
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
 // ---------------------------------------
 // SYCL_DEVICE_FILTER support
 
@@ -424,6 +425,7 @@ bool device_filter_list::deviceNumberCompatible(int DeviceNum) {
         return (!Filter.DeviceNum) || (Filter.DeviceNum.value() == DeviceNum);
       });
 }
+#endif // __INTEL_PREVIEW_BREAKING_CHANGES
 
 } // namespace detail
 } // namespace _V1

sycl/source/detail/filter_selector_impl.hpp

@@ -23,7 +23,11 @@ namespace ext {
 namespace oneapi {
 namespace detail {
 
+#ifdef __INTEL_PREVIEW_BREAKING_CHANGES
+typedef struct sycl::detail::ods_target filter;
+#else
 typedef struct sycl::detail::device_filter filter;
+#endif
 
 class filter_selector_impl {
 public:

sycl/source/detail/global_handler.cpp

@@ -202,10 +202,13 @@ std::vector<PluginPtr> &GlobalHandler::getPlugins() {
   enableOnCrashStackPrinting();
   return getOrCreate(MPlugins);
 }
+
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
 device_filter_list &
 GlobalHandler::getDeviceFilterList(const std::string &InitValue) {
   return getOrCreate(MDeviceFilterList, InitValue);
 }
+#endif
 
 ods_target_list &
 GlobalHandler::getOneapiDeviceSelectorTargets(const std::string &InitValue) {

sycl/source/detail/global_handler.hpp

@@ -23,7 +23,9 @@ class Scheduler;
 class ProgramManager;
 class Sync;
 class plugin;
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
 class device_filter_list;
+#endif
 class ods_target_list;
 class XPTIRegistry;
 class ThreadPool;
@@ -70,7 +72,9 @@ class GlobalHandler {
   std::mutex &getPlatformMapMutex();
   std::mutex &getFilterMutex();
   std::vector<PluginPtr> &getPlugins();
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
   device_filter_list &getDeviceFilterList(const std::string &InitValue);
+#endif
   ods_target_list &getOneapiDeviceSelectorTargets(const std::string &InitValue);
   XPTIRegistry &getXPTIRegistry();
   ThreadPool &getHostTaskThreadPool();
@@ -121,7 +125,9 @@ class GlobalHandler {
   InstWithLock<std::mutex> MPlatformMapMutex;
   InstWithLock<std::mutex> MFilterMutex;
   InstWithLock<std::vector<PluginPtr>> MPlugins;
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
   InstWithLock<device_filter_list> MDeviceFilterList;
+#endif
   InstWithLock<ods_target_list> MOneapiDeviceSelectorTargets;
   InstWithLock<XPTIRegistry> MXPTIRegistry;
   // Thread pool for host task and event callbacks execution

sycl/source/detail/pi.cpp

@@ -291,26 +291,18 @@ 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();
   ods_target_list *OdsTargetList = SYCLConfig<ONEAPI_DEVICE_SELECTOR>::get();
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
+  device_filter_list *FilterList = SYCLConfig<SYCL_DEVICE_FILTER>::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);
-    PluginNames.emplace_back(__SYCL_UR_PLUGIN_NAME, backend::all);
-    PluginNames.emplace_back(__SYCL_NATIVE_CPU_PLUGIN_NAME,
-                             backend::ext_oneapi_native_cpu);
-  } else if (FilterList) {
+  }
+  if (FilterList) {
     std::vector<device_filter> Filters = FilterList->get();
     bool OpenCLFound = false;
     bool LevelZeroFound = false;
@@ -355,6 +347,19 @@ std::vector<std::pair<std::string, backend>> findPlugins() {
       }
       PluginNames.emplace_back(__SYCL_UR_PLUGIN_NAME, backend::all);
     }
+    return PluginNames;
+  }
+#endif // __INTEL_PREVIEW_BREAKING_CHANGES
+  if (!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);
+    PluginNames.emplace_back(__SYCL_UR_PLUGIN_NAME, backend::all);
+    PluginNames.emplace_back(__SYCL_NATIVE_CPU_PLUGIN_NAME,
+                             backend::ext_oneapi_native_cpu);
+
   } else {
     ods_target_list &list = *OdsTargetList;
     if (list.backendCompatible(backend::opencl)) {
@@ -368,10 +373,12 @@ std::vector<std::pair<std::string, backend>> findPlugins() {
       PluginNames.emplace_back(__SYCL_CUDA_PLUGIN_NAME,
                                backend::ext_oneapi_cuda);
     }
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
     if (list.backendCompatible(backend::ext_intel_esimd_emulator)) {
       PluginNames.emplace_back(__SYCL_ESIMD_EMULATOR_PLUGIN_NAME,
                                backend::ext_intel_esimd_emulator);
     }
+#endif
     if (list.backendCompatible(backend::ext_oneapi_hip)) {
       PluginNames.emplace_back(__SYCL_HIP_PLUGIN_NAME, backend::ext_oneapi_hip);
     }

sycl/source/detail/platform_impl.cpp

@@ -206,10 +206,6 @@ std::vector<platform> platform_impl::get_platforms() {
   return Platforms;
 }
 
-// Filter out the devices that are not compatible with SYCL_DEVICE_FILTER or
-// ONEAPI_DEVICE_SELECTOR This function matches devices in the order of backend,
-// device_type, and device_num. The device_filter and ods_target structs pun for
-// each other, as do device_filter_list and ods_target_list.
 // Since ONEAPI_DEVICE_SELECTOR admits negative filters, we use type traits
 // to distinguish the case where we are working with ONEAPI_DEVICE_SELECTOR
 // in the places where the functionality diverges between these two
@@ -222,9 +218,6 @@ std::vector<int> platform_impl::filterDeviceFilter(
     ListT *FilterList) const {
 
   constexpr bool is_ods_target = std::is_same_v<FilterT, ods_target>;
-  // There are some differences in implementation between SYCL_DEVICE_FILTER
-  // and ONEAPI_DEVICE_SELECTOR so we use if constexpr to select the
-  // appropriate execution path if we are dealing with the latter variable.
 
   if constexpr (is_ods_target) {
 
@@ -476,10 +469,13 @@ static std::vector<device> amendDeviceAndSubDevices(
 std::vector<device>
 platform_impl::get_devices(info::device_type DeviceType) const {
   std::vector<device> Res;
+
+  ods_target_list *OdsTargetList = SYCLConfig<ONEAPI_DEVICE_SELECTOR>::get();
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
   // Will we be filtering with SYCL_DEVICE_FILTER or ONEAPI_DEVICE_SELECTOR ?
   // We do NOT attempt to support both simultaneously.
-  ods_target_list *OdsTargetList = SYCLConfig<ONEAPI_DEVICE_SELECTOR>::get();
   device_filter_list *FilterList = SYCLConfig<SYCL_DEVICE_FILTER>::get();
+#endif
 
   if (is_host() && (DeviceType == info::device_type::host ||
                     DeviceType == info::device_type::all)) {
@@ -535,21 +531,25 @@ platform_impl::get_devices(info::device_type DeviceType) const {
     applyAllowList(PiDevices, MPlatform, MPlugin);
 
   // The first step is to filter out devices that are not compatible with
-  // SYCL_DEVICE_FILTER or ONEAPI_DEVICE_SELECTOR. This is also the mechanism by
-  // which top level device ids are assigned.
+  // ONEAPI_DEVICE_SELECTOR. This is also the mechanism by which top level
+  // device ids are assigned.
   std::vector<int> PlatformDeviceIndices;
   if (OdsTargetList) {
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
     if (FilterList) {
       throw sycl::exception(sycl::make_error_code(errc::invalid),
                             "ONEAPI_DEVICE_SELECTOR cannot be used in "
                             "conjunction with SYCL_DEVICE_FILTER");
     }
+#endif
     PlatformDeviceIndices = filterDeviceFilter<ods_target_list, ods_target>(
         PiDevices, OdsTargetList);
+#ifndef __INTEL_PREVIEW_BREAKING_CHANGES
   } else if (FilterList) {
     PlatformDeviceIndices =
         filterDeviceFilter<device_filter_list, device_filter>(PiDevices,
                                                               FilterList);
+#endif
   }
 
   // The next step is to inflate the filtered PIDevices into SYCL Device