[SYCL] Provide extension to query for unsupported platforms

sycl/doc/extensions/experimental/sycl_ext_oneapi_get_unsupported_platforms.asciidoc

@@ -0,0 +1,123 @@
+= sycl_ext_oneapi_get_unsupported_platforms
+
+:source-highlighter: coderay
+:coderay-linenums-mode: table
+
+// This section needs to be after the document title.
+:doctype: book
+:toc2:
+:toc: left
+:encoding: utf-8
+:lang: en
+:dpcpp: pass:[DPC++]
+
+// Set the default source code type in this document to C++,
+// for syntax highlighting purposes. This is needed because
+// docbook uses c++ and html5 uses cpp.
+:language: {basebackend@docbook:c++:cpp}
+
+
+== Notice
+
+[%hardbreaks]
+Copyright (C) 2024 Intel Corporation. All rights reserved.
+
+Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are trademarks
+of The Khronos Group Inc. OpenCL(TM) is a trademark of Apple Inc. used by
+permission by Khronos.
+
+
+== Contact
+
+To report problems with this extension, please open a new issue at:
+
+https://github.com/intel/llvm/issues
+
+
+== Dependencies
+
+This extension is written against the SYCL 2020 revision 8 specification. All
+references below to the "core SYCL specification" or to section numbers in the
+SYCL specification refer to that revision.
+
+
+== Status
+
+This is an experimental extension specification, intended to provide early
+access to features and gather community feedback. Interfaces defined in this
+specification are implemented in {dpcpp}, but they are not finalized and may
+change incompatibly in future versions of {dpcpp} without prior notice.
+*Shipping software products should not rely on APIs defined in this
+specification.*
+
+
+== Overview
+
+The implementation of `sycl::platform` already allows querying for supported
+platforms - `static std::vector<platform> get_platforms()` - which returns all
+available SYCL platforms in the system (the resulting vector always contains a
+single SYCL host platform instance). This extension adds an API entry to list
+all unsupported platforms; the platform is considered unsupported if it is
+non-SYCL, or does not have any devices associated.
+
+This extension exists to solve a specific problem: listing of all platforms
+(supported and not) in verbose mode of `sycl-ls` binary.
+
+
+== Specification
+
+=== Feature test macro
+
+This extension provides a feature-test macro as described in the core SYCL
+specification. An implementation supporting this extension must predefine the
+macro `SYCL_EXT_ONEAPI_GET_UNSUPPORTED_PLATFORMS` to one of the values defined in
+the table below. Applications can test for the existence of this macro to
+determine if the implementation supports this feature, or applications can test
+the macro's value to determine which of the extension's features the
+implementation supports.
+
+[%header,cols="1,5"]
+|===
+|Value
+|Description
+
+|1
+|The API of this experimental extension is not versioned, so the feature-test
+macro always has this value.
+|===
+
+=== New SYCL platform API
+
+This extension adds the following new API to the existing `sycl::platform` class:
+
+[source, c++]
+----
+namespace sycl {
+
+class platform {
+  ...
+
+  static std::vector<platform> ext_oneapi_get_unsupported_platforms();
+
+  ...
+}
+
+} // namespace sycl
+----
+
+The new API has the following behaviour:
+
+--
+[options="header"]
+|====
+| Function Definition | Description
+a| 
+[source, c++]
+----
+static std::vector<platform> ext_oneapi_get_unsupported_platforms();
+----
+| Returns a vector containing all unsupported (non-SYCL, or device-less)
+platforms in the system.
+
+|====
+--

sycl/include/sycl/platform.hpp

@@ -197,7 +197,7 @@ class __SYCL_EXPORT platform : public detail::OwnerLessBase<platform> {
   /// Returns all unsupported (non-SYCL) platforms in the system.
   ///
   /// \return a vector of all unsupported non-SYCL platforms.
-  static std::vector<platform> get_unsupported_platforms();
+  static std::vector<platform> ext_oneapi_get_unsupported_platforms();
 
   /// Returns the backend associated with this platform.
   ///

sycl/source/detail/platform_impl.cpp

@@ -96,8 +96,10 @@ static bool IsBannedPlatform(platform Platform) {
          IsMatchingOpenCL(Platform, "AMD Accelerated Parallel Processing");
 }
 
-// Get the vector of platforms supported by a given UR plugin
-// replace uses of this with a helper in plugin object, the plugin
+// When `Supported` is `true` gets the vector of platforms supported by a given
+// UR `Plugin`. Otherwise a vector of all unsupported (non-SYCL, or
+// device-less) platforms.
+// Replace uses of this with a helper in plugin object, the plugin
 // objects will own the ur adapter handles and they'll need to pass them to
 // urPlatformsGet - so urPlatformsGet will need to be wrapped with a helper
 std::vector<platform> platform_impl::getPluginPlatforms(PluginPtr &Plugin,

sycl/source/feature_test.hpp.in

@@ -108,6 +108,7 @@ inline namespace _V1 {
 #define SYCL_EXT_ONEAPI_RAW_KERNEL_ARG 1
 #define SYCL_EXT_ONEAPI_PROFILING_TAG 1
 #define SYCL_EXT_ONEAPI_ENQUEUE_NATIVE_COMMAND 1
+#define SYCL_EXT_ONEAPI_GET_UNSUPPORTED_PLATFORMS 1
 // In progress yet
 #define SYCL_EXT_ONEAPI_ATOMIC16 0
 

sycl/source/platform.cpp

@@ -52,7 +52,7 @@ std::vector<platform> platform::get_platforms() {
   return detail::platform_impl::get_platforms();
 }
 
-std::vector<platform> platform::get_unsupported_platforms() {
+std::vector<platform> platform::ext_oneapi_get_unsupported_platforms() {
   return detail::platform_impl::get_unsupported_platforms();
 }
 

sycl/test/abi/sycl_symbols_linux.dump

@@ -3545,7 +3545,7 @@ _ZN4sycl3_V17samplerC1EP11_cl_samplerRKNS0_7contextE
 _ZN4sycl3_V17samplerC2ENS0_29coordinate_normalization_modeENS0_15addressing_modeENS0_14filtering_modeERKNS0_13property_listE
 _ZN4sycl3_V17samplerC2EP11_cl_samplerRKNS0_7contextE
 _ZN4sycl3_V18platform13get_platformsEv
-_ZN4sycl3_V18platform25get_unsupported_platformsEv
+_ZN4sycl3_V18platform36ext_oneapi_get_unsupported_platformsEv
 _ZN4sycl3_V18platformC1EP15_cl_platform_id
 _ZN4sycl3_V18platformC1ERKNS0_15device_selectorE
 _ZN4sycl3_V18platformC1ERKNS0_6deviceE

sycl/test/abi/sycl_symbols_windows.dump

@@ -4035,7 +4035,7 @@
 ?get_platform@context@_V1@sycl@@QEBA?AVplatform@23@XZ
 ?get_platform@device@_V1@sycl@@QEBA?AVplatform@23@XZ
 ?get_platforms@platform@_V1@sycl@@SA?AV?$vector@Vplatform@_V1@sycl@@V?$allocator@Vplatform@_V1@sycl@@@std@@@std@@XZ
-?get_unsupported_platforms@platform@_V1@sycl@@SA?AV?$vector@Vplatform@_V1@sycl@@V?$allocator@Vplatform@_V1@sycl@@@std@@@std@@XZ
+?ext_oneapi_get_unsupported_platforms@platform@_V1@sycl@@SA?AV?$vector@Vplatform@_V1@sycl@@V?$allocator@Vplatform@_V1@sycl@@@std@@@std@@XZ
 ?get_pointer_device@_V1@sycl@@YA?AVdevice@12@PEBXAEBVcontext@12@@Z
 ?get_pointer_type@_V1@sycl@@YA?AW4alloc@usm@12@PEBXAEBVcontext@12@@Z
 ?get_precision@stream@_V1@sycl@@QEBA_KXZ

sycl/tools/sycl-ls/sycl-ls.cpp

@@ -430,7 +430,8 @@ int main(int argc, char **argv) {
       std::cout << "\nPlatforms: " << Platforms.size() << std::endl;
       printVerbosePlatformInfo(Platforms, DeviceNums, SuppressNumberPrinting);
 
-      const auto &UnsupportedPlatforms = platform::get_unsupported_platforms();
+      const auto &UnsupportedPlatforms =
+          platform::ext_oneapi_get_unsupported_platforms();
       std::cout << "\nUnsupported Platforms: " << UnsupportedPlatforms.size()
                 << std::endl;
       printVerbosePlatformInfo(UnsupportedPlatforms, DeviceNums,