From 34b4aa658f1b7c4098c4930ba4302171a8a41c03 Mon Sep 17 00:00:00 2001 From: Jakub Chlanda Date: Thu, 12 Sep 2024 12:51:39 +0000 Subject: [PATCH 1/2] [SYCL] Provide extension to query for unsupported platforms --- ..._oneapi_get_unsupported_platforms.asciidoc | 123 ++++++++++++++++++ sycl/include/sycl/platform.hpp | 2 +- sycl/source/detail/platform_impl.cpp | 6 +- sycl/source/feature_test.hpp.in | 1 + sycl/source/platform.cpp | 2 +- sycl/test/abi/sycl_symbols_linux.dump | 2 +- sycl/test/abi/sycl_symbols_windows.dump | 2 +- sycl/tools/sycl-ls/sycl-ls.cpp | 3 +- 8 files changed, 134 insertions(+), 7 deletions(-) create mode 100644 sycl/doc/extensions/experimental/sycl_ext_oneapi_get_unsupported_platforms.asciidoc diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_get_unsupported_platforms.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_get_unsupported_platforms.asciidoc new file mode 100644 index 0000000000000..d2d0aca502d7e --- /dev/null +++ b/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 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 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 ext_oneapi_get_unsupported_platforms(); +---- +| Returns a vector containing all unsupported (non-SYCL, or device-less) +platforms in the system. + +|==== +-- diff --git a/sycl/include/sycl/platform.hpp b/sycl/include/sycl/platform.hpp index cc99804680487..4556ba99b2b86 100644 --- a/sycl/include/sycl/platform.hpp +++ b/sycl/include/sycl/platform.hpp @@ -197,7 +197,7 @@ class __SYCL_EXPORT platform : public detail::OwnerLessBase { /// Returns all unsupported (non-SYCL) platforms in the system. /// /// \return a vector of all unsupported non-SYCL platforms. - static std::vector get_unsupported_platforms(); + static std::vector ext_oneapi_get_unsupported_platforms(); /// Returns the backend associated with this platform. /// diff --git a/sycl/source/detail/platform_impl.cpp b/sycl/source/detail/platform_impl.cpp index fea1abbf3a01e..623718578492f 100644 --- a/sycl/source/detail/platform_impl.cpp +++ b/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_impl::getPluginPlatforms(PluginPtr &Plugin, diff --git a/sycl/source/feature_test.hpp.in b/sycl/source/feature_test.hpp.in index a61e504eb5e4c..d97557670ca14 100644 --- a/sycl/source/feature_test.hpp.in +++ b/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 diff --git a/sycl/source/platform.cpp b/sycl/source/platform.cpp index b9ec5073fb7ea..cad690314cf4b 100644 --- a/sycl/source/platform.cpp +++ b/sycl/source/platform.cpp @@ -52,7 +52,7 @@ std::vector platform::get_platforms() { return detail::platform_impl::get_platforms(); } -std::vector platform::get_unsupported_platforms() { +std::vector platform::ext_oneapi_get_unsupported_platforms() { return detail::platform_impl::get_unsupported_platforms(); } diff --git a/sycl/test/abi/sycl_symbols_linux.dump b/sycl/test/abi/sycl_symbols_linux.dump index ec6ec2096403f..b5d4eb2beb97e 100644 --- a/sycl/test/abi/sycl_symbols_linux.dump +++ b/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 diff --git a/sycl/test/abi/sycl_symbols_windows.dump b/sycl/test/abi/sycl_symbols_windows.dump index 55ce460c64559..633c75c84bc2a 100644 --- a/sycl/test/abi/sycl_symbols_windows.dump +++ b/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 diff --git a/sycl/tools/sycl-ls/sycl-ls.cpp b/sycl/tools/sycl-ls/sycl-ls.cpp index c062c26b96fb3..96b73f18ebf62 100644 --- a/sycl/tools/sycl-ls/sycl-ls.cpp +++ b/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, From 413dd3904e5879f715e6b461634a9d1f25445346 Mon Sep 17 00:00:00 2001 From: Jakub Chlanda Date: Fri, 13 Sep 2024 10:16:24 +0000 Subject: [PATCH 2/2] Remove mentions of host platform --- .../sycl_ext_oneapi_get_unsupported_platforms.asciidoc | 5 ++--- sycl/source/detail/platform_impl.hpp | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_get_unsupported_platforms.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_get_unsupported_platforms.asciidoc index d2d0aca502d7e..2ebce1d5c0867 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_get_unsupported_platforms.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_get_unsupported_platforms.asciidoc @@ -55,9 +55,8 @@ specification.* The implementation of `sycl::platform` already allows querying for supported platforms - `static std::vector 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 +available SYCL platforms in the system. 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 diff --git a/sycl/source/detail/platform_impl.hpp b/sycl/source/detail/platform_impl.hpp index 41be819e0e133..ba78ac5eb58b1 100644 --- a/sycl/source/detail/platform_impl.hpp +++ b/sycl/source/detail/platform_impl.hpp @@ -117,9 +117,8 @@ class platform_impl { /// Returns all available SYCL platforms in the system. /// - /// By default the resulting vector always contains a single SYCL host - /// platform instance. There are means to override this behavior for testing - /// purposes. See environment variables guide for up-to-date instructions. + /// There are means to override this behavior for testing purposes. See + /// environment variables guide for up-to-date instructions. /// /// \return a vector of all available SYCL platforms. static std::vector get_platforms();