Replace outdated SYCL_DEVICE_FILTER with ONEAPI_DEVICE_SELECTOR (#484)

Co-authored-by: Dai-Ni Hsieh <[email protected]>

docs/building_the_project.rst

@@ -219,7 +219,7 @@ With the AMD rocBLAS backend:
             -DHIP_TARGETS=gfx90a                                         \ # Specify the targetted device architectures
             [-DREF_BLAS_ROOT=<reference_blas_install_prefix>]              # required only for testing
    cmake --build .
-   export SYCL_DEVICE_FILTER=HIP
+   export ONEAPI_DEVICE_SELECTOR="hip:gpu"
    ctest
    cmake --install . --prefix <path_to_install_dir>                        # required to have full package structure
 
@@ -429,7 +429,7 @@ The following table provides details of CMake options and their default values:
 
 .. note::
   When building with clang++ for AMD backends, you must additionally set
-  ``SYCL_DEVICE_FILTER`` to ``HIP`` and provide ``-DHIP_TARGETS`` according to
+  ``ONEAPI_DEVICE_SELECTOR`` to ``hip:gpu`` and provide ``-DHIP_TARGETS`` according to
   the targeted hardware. This backend has only been tested for the ``gfx90a``
   architecture (MI210) at the time of writing.
 

examples/README.md

@@ -23,7 +23,7 @@ The example executable naming convention follows `example_<$domain>_<$routine>_<
 
 Run-time dispatching examples with mklcpu backend
 ```
-$ export SYCL_DEVICE_FILTER=cpu
+$ export ONEAPI_DEVICE_SELECTOR="opencl:cpu"
 $ ./bin/example_blas_gemm_usm
 
 ########################################################################
@@ -40,8 +40,8 @@ $ ./bin/example_blas_gemm_usm
 # Using single precision (float) data type
 #
 # Device will be selected during runtime.
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 #
 ########################################################################
 
@@ -76,7 +76,7 @@ BLAS GEMM USM example ran OK.
 ```
 Run-time dispatching examples with mklgpu backend
 ```
-$ export SYCL_DEVICE_FILTER=gpu
+$ export ONEAPI_DEVICE_SELECTOR="level_zero:gpu"
 $ ./bin/example_blas_gemm_usm
 
 ########################################################################
@@ -93,8 +93,8 @@ $ ./bin/example_blas_gemm_usm
 # Using single precision (float) data type
 #
 # Device will be selected during runtime.
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 #
 ########################################################################
 
@@ -188,7 +188,7 @@ BLAS GEMM USM example ran OK on MKLCPU and CUBLAS
 ## lapack 
 Run-time dispatching example with mklgpu backend:
 ```
-$ export SYCL_DEVICE_FILTER=gpu
+$ export ONEAPI_DEVICE_SELECTOR="level_zero:gpu"
 $ ./bin/example_lapack_getrs_usm
 
 ########################################################################
@@ -206,8 +206,8 @@ $ ./bin/example_lapack_getrs_usm
 # Using single precision (float) data type
 #
 # Device will be selected during runtime.
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 #
 ########################################################################
 
@@ -289,7 +289,7 @@ LAPACK GETRS USM example ran OK on MKLCPU and CUSOLVER
 ## rng
 Run-time dispatching example with mklgpu backend:
 ```
-$ export SYCL_DEVICE_FILTER=gpu
+$ export ONEAPI_DEVICE_SELECTOR="level_zero:gpu"
 $ ./bin/example_rng_uniform_usm
 
 ########################################################################
@@ -302,8 +302,8 @@ $ ./bin/example_rng_uniform_usm
 # Using single precision (float) data type
 #
 # Device will be selected during runtime.
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 #
 ########################################################################
 
@@ -357,7 +357,7 @@ Random number generator example with uniform distribution ran OK on MKLCPU and C
 Compile-time dispatching example with MKLGPU backend
 
 ```none
-$ SYCL_DEVICE_FILTER=gpu ./bin/example_dft_complex_fwd_buffer_mklgpu
+$ ONEAPI_DEVICE_SELECTOR="level_zero:gpu" ./bin/example_dft_complex_fwd_buffer_mklgpu
 
 ########################################################################
 # Complex out-of-place forward transform for Buffer API's example:
@@ -370,8 +370,8 @@ $ SYCL_DEVICE_FILTER=gpu ./bin/example_dft_complex_fwd_buffer_mklgpu
 #
 # For Intel GPU with Intel MKLGPU backend.
 #
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 ########################################################################
 
 Running DFT Complex forward out-of-place buffer example
@@ -384,7 +384,7 @@ DFT Complex USM example ran OK on MKLGPU
 Runtime dispatching example with MKLGPU, cuFFT, rocFFT and portFFT backends:
 
 ```none
-$ SYCL_DEVICE_FILTER=gpu ./bin/example_dft_real_fwd_usm
+$ ONEAPI_DEVICE_SELECTOR="level_zero:gpu" ./bin/example_dft_real_fwd_usm
 
 ########################################################################
 # DFT complex in-place forward transform with USM API example:
@@ -396,8 +396,8 @@ $ SYCL_DEVICE_FILTER=gpu ./bin/example_dft_real_fwd_usm
 # Using single precision (float) data type
 #
 # Device will be selected during runtime.
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 #
 ########################################################################
 
@@ -409,7 +409,7 @@ DFT example ran OK
 ```
 
 ```none
-$ SYCL_DEVICE_FILTER=gpu ./bin/example_dft_real_fwd_usm
+$ ONEAPI_DEVICE_SELECTOR="level_zero:gpu" ./bin/example_dft_real_fwd_usm
 
 ########################################################################
 # DFT complex in-place forward transform with USM API example:
@@ -421,8 +421,8 @@ $ SYCL_DEVICE_FILTER=gpu ./bin/example_dft_real_fwd_usm
 # Using single precision (float) data type
 #
 # Device will be selected during runtime.
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 #
 ########################################################################
 
@@ -446,8 +446,8 @@ $ ./bin/example_dft_real_fwd_usm
 # Using single precision (float) data type
 #
 # Device will be selected during runtime.
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 #
 ########################################################################
 
@@ -470,8 +470,8 @@ $ LD_LIBRARY_PATH=lib/:$LD_LIBRARY_PATH ./bin/example_dft_real_fwd_usm
 # Using single precision (float) data type
 #
 # Device will be selected during runtime.
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 #
 ########################################################################
 
@@ -487,7 +487,7 @@ Unsupported Configuration:
 
 Run-time dispatching examples with mklcpu backend
 ```
-$ export SYCL_DEVICE_FILTER=cpu
+$ export ONEAPI_DEVICE_SELECTOR="opencl:cpu"
 $ ./bin/example_sparse_blas_gemv_usm
 
 ########################################################################
@@ -504,8 +504,8 @@ $ ./bin/example_sparse_blas_gemv_usm
 # Using single precision (float) data type
 # 
 # Device will be selected during runtime.
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 # 
 ########################################################################
 
@@ -525,7 +525,7 @@ Sparse BLAS GEMV USM example ran OK.
 
 Run-time dispatching examples with mklgpu backend
 ```
-$ export SYCL_DEVICE_FILTER=gpu
+$ export ONEAPI_DEVICE_SELECTOR="level_zero:gpu"
 $ ./bin/example_sparse_blas_gemv_usm
 
 ########################################################################
@@ -542,8 +542,8 @@ $ ./bin/example_sparse_blas_gemv_usm
 # Using single precision (float) data type
 # 
 # Device will be selected during runtime.
-# The environment variable SYCL_DEVICE_FILTER can be used to specify
-# SYCL device
+# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify
+# available devices
 # 
 ########################################################################
 
@@ -563,7 +563,7 @@ Sparse BLAS GEMV USM example ran OK.
 
 Compile-time dispatching example with mklcpu backend
 ```
-$ export SYCL_DEVICE_FILTER=cpu
+$ export ONEAPI_DEVICE_SELECTOR="opencl:cpu"
 $ ./bin/example_sparse_blas_gemv_usm_mklcpu
 
 ########################################################################

examples/blas/run_time_dispatching/level3/CMakeLists.txt

@@ -17,22 +17,22 @@
 # SPDX-License-Identifier: Apache-2.0
 #===============================================================================
 
-# NOTE: user needs to set env var SYCL_DEVICE_FILTER to use runtime example without specifying backend in CMake
-# $ENV{SYCL_DEVICE_FILTER}
+# NOTE: user needs to set env var ONEAPI_DEVICE_SELECTOR to use runtime example without specifying backend in CMake
+# $ENV{ONEAPI_DEVICE_SELECTOR}
 
 
 # Build object from all example sources
 set(BLAS_RT_SOURCES "gemm_usm")
 
 # Set up for the right backend for run-time dispatching examples
 # If users build more than one backend (i.e. mklcpu and mklgpu, or mklcpu and CUDA), they may need to
-# overwrite SYCL_DEVICE_FILTER in their environment to run on the desired backend
+# overwrite ONEAPI_DEVICE_SELECTOR in their environment to run on the desired backend
 set(DEVICE_FILTERS "")
 if(ENABLE_MKLCPU_BACKEND)
-  list(APPEND DEVICE_FILTERS "cpu")
+  list(APPEND DEVICE_FILTERS "opencl:cpu")
 endif()
 if(ENABLE_MKLGPU_BACKEND)
-  list(APPEND DEVICE_FILTERS "gpu")
+  list(APPEND DEVICE_FILTERS "level_zero:gpu")
 endif()
 if(ENABLE_CUBLAS_BACKEND)
   list(APPEND DEVICE_FILTERS "cuda:gpu")
@@ -41,7 +41,7 @@ if(ENABLE_ROCBLAS_BACKEND)
   list(APPEND DEVICE_FILTERS "hip:gpu")
 endif()
 
-message(STATUS "SYCL_DEVICE_FILTER will be set to the following value(s): [${DEVICE_FILTERS}] for run-time dispatching examples")
+message(STATUS "ONEAPI_DEVICE_SELECTOR will be set to the following value(s): [${DEVICE_FILTERS}] for run-time dispatching examples")
 
 foreach(blas_rt_source ${BLAS_RT_SOURCES})
   add_executable(example_${domain}_${blas_rt_source} ${blas_rt_source}.cpp)
@@ -68,7 +68,7 @@ foreach(blas_rt_source ${BLAS_RT_SOURCES})
     add_test(NAME ${domain}/EXAMPLE/RT/${blas_rt_source}/${device_filter} COMMAND example_${domain}_${blas_rt_source})
     set_property(TEST ${domain}/EXAMPLE/RT/${blas_rt_source}/${device_filter} PROPERTY
       ENVIRONMENT LD_LIBRARY_PATH=${CMAKE_BINARY_DIR}/lib:$ENV{LD_LIBRARY_PATH}
-      ENVIRONMENT SYCL_DEVICE_FILTER=${device_filter})
+      ENVIRONMENT ONEAPI_DEVICE_SELECTOR=${device_filter})
   endforeach(device_filter)
 
 endforeach(blas_rt_source)

examples/blas/run_time_dispatching/level3/gemm_usm.cpp

@@ -198,9 +198,9 @@ void print_example_banner() {
     std::cout << "# Using single precision (float) data type" << std::endl;
     std::cout << "# " << std::endl;
     std::cout << "# Device will be selected during runtime." << std::endl;
-    std::cout << "# The environment variable SYCL_DEVICE_FILTER can be used to specify"
+    std::cout << "# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify"
               << std::endl;
-    std::cout << "# SYCL device" << std::endl;
+    std::cout << "# available devices" << std::endl;
     std::cout << "# " << std::endl;
     std::cout << "########################################################################"
               << std::endl;

examples/dft/compile_time_dispatching/complex_fwd_buffer_mklcpu.cpp

@@ -91,8 +91,8 @@ void print_example_banner() {
                  "#\n"
                  "# For Intel CPU with Intel MKLCPU backend.\n"
                  "#\n"
-                 "# The environment variable SYCL_DEVICE_FILTER can be used to specify\n"
-                 "# SYCL device\n"
+                 "# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify\n"
+                 "# available devices\n"
                  "########################################################################\n"
               << std::endl;
 }

examples/dft/compile_time_dispatching/complex_fwd_buffer_mklgpu.cpp

@@ -91,8 +91,8 @@ void print_example_banner() {
                  "#\n"
                  "# For Intel GPU with Intel MKLGPU backend.\n"
                  "#\n"
-                 "# The environment variable SYCL_DEVICE_FILTER can be used to specify\n"
-                 "# SYCL device\n"
+                 "# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify\n"
+                 "# available devices\n"
                  "########################################################################\n"
               << std::endl;
 }

examples/dft/run_time_dispatching/CMakeLists.txt

@@ -17,22 +17,34 @@
 # SPDX-License-Identifier: Apache-2.0
 #===============================================================================
 
-# NOTE: user needs to set env var SYCL_DEVICE_FILTER to use runtime example (no need to specify backend when building with CMake)
+# NOTE: user needs to set env var ONEAPI_DEVICE_SELECTOR to use runtime example (no need to specify backend when building with CMake)
 include(WarningsUtils)
 
 
 # Build object from all example sources
 set(DFT_RT_SOURCES "")
 # Set up for the right backend for run-time dispatching examples
 # If users build more than one backend (i.e. mklcpu and mklgpu, or mklcpu and CUDA), they may need to
-# overwrite SYCL_DEVICE_FILTER in their environment to run on the desired backend
+# overwrite ONEAPI_DEVICE_SELECTOR in their environment to run on the desired backend
 set(DEVICE_FILTERS "")
 if(ENABLE_MKLGPU_BACKEND OR ENABLE_CUFFT_BACKEND OR ENABLE_ROCFFT_BACKEND OR ENABLE_PORTFFT_BACKEND)
   list(APPEND DFT_RT_SOURCES "real_fwd_usm")
-  list(APPEND DEVICE_FILTERS "gpu")
 endif()
 
-message(STATUS "SYCL_DEVICE_FILTER will be set to the following value(s): [${DEVICE_FILTERS}] for run-time dispatching examples")
+if(ENABLE_MKLGPU_BACKEND)
+  list(APPEND DEVICE_FILTERS "level_zero:gpu")
+endif()
+if(ENABLE_PORTFFT_BACKEND)
+  list(APPEND DEVICE_FILTERS "*:gpu")
+endif()
+if(ENABLE_CUFFT_BACKEND)
+  list(APPEND DEVICE_FILTERS "cuda:gpu")
+endif()
+if(ENABLE_ROCFFT_BACKEND)
+  list(APPEND DEVICE_FILTERS "hip:gpu")
+endif()
+
+message(STATUS "ONEAPI_DEVICE_SELECTOR will be set to the following value(s): [${DEVICE_FILTERS}] for run-time dispatching examples")
 
 foreach(dft_rt_sources ${DFT_RT_SOURCES})
   add_executable(example_${domain}_${dft_rt_sources} ${dft_rt_sources}.cpp)
@@ -60,7 +72,7 @@ foreach(dft_rt_sources ${DFT_RT_SOURCES})
     add_test(NAME ${domain}/EXAMPLE/RT/${dft_rt_sources}/${device_filter} COMMAND example_${domain}_${dft_rt_sources})
     set_property(TEST ${domain}/EXAMPLE/RT/${dft_rt_sources}/${device_filter} PROPERTY
       ENVIRONMENT LD_LIBRARY_PATH=${CMAKE_BINARY_DIR}/lib:$ENV{LD_LIBRARY_PATH}
-      ENVIRONMENT SYCL_DEVICE_FILTER=${device_filter})
+      ENVIRONMENT ONEAPI_DEVICE_SELECTOR=${device_filter})
   endforeach(device_filter)
 
 endforeach()

examples/dft/run_time_dispatching/real_fwd_usm.cpp

@@ -90,8 +90,8 @@ void print_example_banner() {
                  "# Using single precision (float) data type\n"
                  "#\n"
                  "# Device will be selected during runtime.\n"
-                 "# The environment variable SYCL_DEVICE_FILTER can be used to specify\n"
-                 "# SYCL device\n"
+                 "# The environment variable ONEAPI_DEVICE_SELECTOR can be used to specify\n"
+                 "# available devices\n"
                  "#\n"
                  "########################################################################\n"
               << std::endl;