From d214c1c9959faa91eb06233f784910ba68ab49fd Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 13 Nov 2025 13:27:11 -0500 Subject: [PATCH 1/2] [SYCL][Doc] Update proposed device index extension Our internal customer who is requesting this feature wants the index returned by this API to match the Level Zero device identifier (which is also an index). This is only possible if the index is per-platform instead of globally unique. --- ...ext_oneapi_platform_device_index.asciidoc} | 73 +++++++++++++++---- 1 file changed, 58 insertions(+), 15 deletions(-) rename sycl/doc/extensions/proposed/{sycl_ext_oneapi_device_index.asciidoc => sycl_ext_oneapi_platform_device_index.asciidoc} (58%) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_index.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_platform_device_index.asciidoc similarity index 58% rename from sycl/doc/extensions/proposed/sycl_ext_oneapi_device_index.asciidoc rename to sycl/doc/extensions/proposed/sycl_ext_oneapi_platform_device_index.asciidoc index 92aa580f06f06..2d63457a944a6 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_index.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_platform_device_index.asciidoc @@ -1,4 +1,4 @@ -= sycl_ext_oneapi_device_index += sycl_ext_oneapi_platform_device_index :source-highlighter: coderay :coderay-linenums-mode: table @@ -37,7 +37,7 @@ https://github.com/intel/llvm/issues == Dependencies -This extension is written against the SYCL 2020 revision 10 specification. +This extension is written against the SYCL 2020 revision 11 specification. All references below to the "core SYCL specification" or to section numbers in the SYCL specification refer to that revision. @@ -57,10 +57,11 @@ specification.* == Overview Some SYCL applications find it more convenient to represent a device as an -integer value rather than using the `device` class. +integer value rather than using the `device` class, where the integer value +represents the index of the device within its platform. The core SYCL specification already allows an application to do this by using the `device` object's index in the list of all devices returned by -`device::get_devices`. +`platform::get_devices`. However, converting between a `device` object and its index could be expensive because the conversion requires a search through all of the devices returned by `get_devices`. @@ -75,7 +76,8 @@ conversion. 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_DEVICE_INDEX` to one of the values defined in the table below. +`SYCL_EXT_ONEAPI_PLATFORM_DEVICE_INDEX` 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. @@ -89,9 +91,9 @@ to determine which of the extension's features the implementation supports. |Initial version of this extension. |=== -=== New member functions in the device class +=== New member function in the device class -This extension adds the following new member functions to the `device` class. +This extension adds the following new member function to the `device` class. [frame=all,grid=none,separator="@"] |==== @@ -100,8 +102,7 @@ a@ ---- class device { // ... - size_t ext_oneapi_to_index() const; - static device ext_oneapi_from_index(size_t index); + size_t ext_oneapi_index_within_platform() const; }; ---- |==== @@ -113,30 +114,49 @@ class device { a@ [source,c++] ---- -size_t ext_oneapi_to_index() const; +size_t ext_oneapi_index_within_platform() const; ---- |==== _Returns:_ If this device is a root device as defined by the core SYCL specification, returns the index that it has in the `std::vector` that is -returned when calling `device::get_devices()`. +returned when calling `platform::get_devices()` on the platform that contains +this device. _Throws:_ An `exception` with the `errc::invalid` error code if this device is not a root device. ''' +=== New member function in the platform class + +This extension adds the following new member function to the `platform` class. + [frame=all,grid=none,separator="@"] |==== a@ [source,c++] ---- -static device ext_oneapi_from_index(size_t index); +class platform { + // ... + device ext_oneapi_index_to_device(size_t index) const; +}; +---- +|==== + +''' + +[frame=all,grid=none,separator="@"] +|==== +a@ +[source,c++] +---- +device ext_oneapi_index_to_device(size_t index) const; ---- |==== _Returns:_ If the `index` is within range of the `std::vector` that is returned -when calling `device::get_devices()`, returns a copy of the `device` object +when calling `platform::get_devices()`, returns a copy of the `device` object which has that index. _Throws:_ An `exception` with the `errc::invalid` error code if the `index` is @@ -145,6 +165,28 @@ out of range. ''' +== {dpcpp} guaranteed compatibility with Level Zero and OpenCL backends + +The contents of this section are non-normative and apply only to the {dpcpp} +implementation. +The device index returned from `device::ext_oneapi_index_within_platform` is +compatible with the index of the underlying backend device when the +`ONEAPI_DEVICE_SELECTOR` environment variable is not set. +Specifically, the following guarantees are provided. + +* When the platform's backend is `backend::ext_oneapi_level_zero`, the index + returned from `device::ext_oneapi_index_within_platform` matches the index of + the device's underlying `ze_device_handle_t` within the list of handles + returned from `zeDeviceGet`. + As a result, the SYCL device index is equivalent to the Level Zero index + returned from `zerTranslateDeviceHandleToIdentifier`. + +* When the platform's backend is `backend::opencl`, the index returned from + `device::ext_oneapi_index_within_platform` matches the index of the device's + underlying `cl_device_id` within the list of IDs returned from + `clGetDeviceIDs`. + + == Example [source,c++] @@ -154,9 +196,10 @@ out of range. int main() { sycl::device d1; // Get the default device. // There is no guarantee this has index 0. + sycl::platform p; // Get the platform containing the default device. - size_t index = d1.ext_oneapi_to_index(); - sycl::device d2 = sycl::device::ext_oneapi_from_index(index); + size_t index = d1.ext_oneapi_index_within_platform(); + sycl::device d2 = p.ext_oneapi_index_to_device(index); assert(d1 == d2); } ---- From f4d3524574a1340320e50113e6d8730dccad3880 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Fri, 14 Nov 2025 08:21:18 -0500 Subject: [PATCH 2/2] Change name of platform member function --- .../proposed/sycl_ext_oneapi_platform_device_index.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_platform_device_index.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_platform_device_index.asciidoc index 2d63457a944a6..ccb56f9e26a05 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_platform_device_index.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_platform_device_index.asciidoc @@ -139,7 +139,7 @@ a@ ---- class platform { // ... - device ext_oneapi_index_to_device(size_t index) const; + device ext_oneapi_device_at_index(size_t index) const; }; ---- |==== @@ -151,7 +151,7 @@ class platform { a@ [source,c++] ---- -device ext_oneapi_index_to_device(size_t index) const; +device ext_oneapi_device_at_index(size_t index) const; ---- |==== @@ -199,7 +199,7 @@ int main() { sycl::platform p; // Get the platform containing the default device. size_t index = d1.ext_oneapi_index_within_platform(); - sycl::device d2 = p.ext_oneapi_index_to_device(index); + sycl::device d2 = p.ext_oneapi_device_at_index(index); assert(d1 == d2); } ----