[SYCL] Add deprecation warnings for unstable keys of SYCL_DEVICE_ALLOWLIST (#4455)

This patch adds deprecation warnings for DeviceName and PlatformName
keys of SYCL_DEVICE_ALLOWLIST and suggests using stable BackendName,
DeviceType and DeviceVendorId keys instead of them

Author: dm-vodopyanov

sycl/source/detail/allowlist.cpp

@@ -77,6 +77,12 @@ AllowListParsedT parseAllowList(const std::string &AllowListRaw) {
                               "doc/EnvironmentVariables.md",
                               PI_INVALID_VALUE);
 
+  const std::string &DeprecatedKeyNameDeviceName = DeviceNameKeyName;
+  const std::string &DeprecatedKeyNamePlatformName = PlatformNameKeyName;
+
+  bool IsDeprecatedKeyNameDeviceNameWasUsed = false;
+  bool IsDeprecatedKeyNamePlatformNameWasUsed = false;
+
   while ((KeyEnd = AllowListRaw.find(DelimiterBtwKeyAndValue, KeyStart)) !=
          std::string::npos) {
     if ((ValueStart = AllowListRaw.find_first_not_of(
@@ -96,6 +102,13 @@ AllowListParsedT parseAllowList(const std::string &AllowListRaw) {
           PI_INVALID_VALUE);
     }
 
+    if (Key == DeprecatedKeyNameDeviceName) {
+      IsDeprecatedKeyNameDeviceNameWasUsed = true;
+    }
+    if (Key == DeprecatedKeyNamePlatformName) {
+      IsDeprecatedKeyNamePlatformNameWasUsed = true;
+    }
+
     bool ShouldAllocateNewDeviceDescMap = false;
 
     std::string Value;
@@ -241,6 +254,27 @@ AllowListParsedT parseAllowList(const std::string &AllowListRaw) {
     }
   }
 
+  if (IsDeprecatedKeyNameDeviceNameWasUsed &&
+      IsDeprecatedKeyNamePlatformNameWasUsed) {
+    std::cout << "\nWARNING: " << DeprecatedKeyNameDeviceName << " and "
+              << DeprecatedKeyNamePlatformName
+              << " in SYCL_DEVICE_ALLOWLIST are deprecated. ";
+  } else if (IsDeprecatedKeyNameDeviceNameWasUsed) {
+    std::cout << "\nWARNING: " << DeprecatedKeyNameDeviceName
+              << " in SYCL_DEVICE_ALLOWLIST is deprecated. ";
+  } else if (IsDeprecatedKeyNamePlatformNameWasUsed) {
+    std::cout << "\nWARNING: " << DeprecatedKeyNamePlatformName
+              << " in SYCL_DEVICE_ALLOWLIST is deprecated. ";
+  }
+  if (IsDeprecatedKeyNameDeviceNameWasUsed ||
+      IsDeprecatedKeyNamePlatformNameWasUsed) {
+    std::cout << "Please use " << BackendNameKeyName << ", "
+              << DeviceTypeKeyName << " and " << DeviceVendorIdKeyName
+              << " instead. For details, please refer to "
+                 "https://github.com/intel/llvm/blob/sycl/sycl/doc/"
+                 "EnvironmentVariables.md\n\n";
+  }
+
   return AllowListParsed;
 }
 

sycl/unittests/allowlist/ParseAllowList.cpp

@@ -267,3 +267,48 @@ TEST(ParseAllowListTests, CheckExceptionIsThrownForValueWOColonDelim) {
     FAIL() << "Expected sycl::runtime_error";
   }
 }
+
+TEST(ParseAllowListTests, CheckDeviceNameDeprecationWarning) {
+  testing::internal::CaptureStdout();
+  sycl::detail::parseAllowList("DeviceName:{{regex}}");
+  std::string ActualOutput = testing::internal::GetCapturedStdout();
+  EXPECT_EQ("\nWARNING: DeviceName in SYCL_DEVICE_ALLOWLIST is deprecated. "
+            "Please use BackendName, DeviceType and DeviceVendorId instead. "
+            "For details, please refer to "
+            "https://github.com/intel/llvm/blob/sycl/sycl/doc/"
+            "EnvironmentVariables.md\n\n",
+            ActualOutput);
+}
+
+TEST(ParseAllowListTests, CheckPlatformNameDeprecationWarning) {
+  testing::internal::CaptureStdout();
+  sycl::detail::parseAllowList("PlatformName:{{regex}}");
+  std::string ActualOutput = testing::internal::GetCapturedStdout();
+  EXPECT_EQ("\nWARNING: PlatformName in SYCL_DEVICE_ALLOWLIST is deprecated. "
+            "Please use BackendName, DeviceType and DeviceVendorId instead. "
+            "For details, please refer to "
+            "https://github.com/intel/llvm/blob/sycl/sycl/doc/"
+            "EnvironmentVariables.md\n\n",
+            ActualOutput);
+}
+
+TEST(ParseAllowListTests, CheckDeviceNameAndPlatformNameDeprecationWarning) {
+  testing::internal::CaptureStdout();
+  sycl::detail::parseAllowList("DeviceName:{{regex}},PlatformName:{{regex}}");
+  std::string ActualOutput = testing::internal::GetCapturedStdout();
+  EXPECT_EQ("\nWARNING: DeviceName and PlatformName in SYCL_DEVICE_ALLOWLIST "
+            "are deprecated. Please use BackendName, DeviceType and "
+            "DeviceVendorId instead. For details, please refer to "
+            "https://github.com/intel/llvm/blob/sycl/sycl/doc/"
+            "EnvironmentVariables.md\n\n",
+            ActualOutput);
+}
+
+TEST(ParseAllowListTests, CheckNoDeprecationWarningForNotDeprecatedKeys) {
+  testing::internal::CaptureStdout();
+  sycl::detail::parseAllowList(
+      "BackendName:level_zero,DeviceType:gpu,DeviceVendorId:0x0000,"
+      "DriverVersion:{{regex1}},PlatformVersion:{{regex2}}");
+  std::string ActualOutput = testing::internal::GetCapturedStdout();
+  EXPECT_EQ("", ActualOutput);
+}