diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_index.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_index.asciidoc new file mode 100644 index 0000000000000..92aa580f06f06 --- /dev/null +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_index.asciidoc @@ -0,0 +1,162 @@ += sycl_ext_oneapi_device_index + +: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++] +:endnote: —{nbsp}end{nbsp}note + +// 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) 2025 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 10 specification. +All references below to the "core SYCL specification" or to section numbers in +the SYCL specification refer to that revision. + + +== Status + +This is a proposed extension specification, intended to gather community +feedback. +Interfaces defined in this specification may not be implemented yet or may be in +a preliminary state. +The specification itself may also change in incompatible ways before it is +finalized. +*Shipping software products should not rely on APIs defined in this +specification.* + + +== Overview + +Some SYCL applications find it more convenient to represent a device as an +integer value rather than using the `device` class. +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`. +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`. +This extension adds functions that make it easy and efficient to do this +conversion. + + +== 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_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. + +[%header,cols="1,5"] +|=== +|Value +|Description + +|1 +|Initial version of this extension. +|=== + +=== New member functions in the device class + +This extension adds the following new member functions to the `device` class. + +[frame=all,grid=none,separator="@"] +|==== +a@ +[source,c++] +---- +class device { + // ... + size_t ext_oneapi_to_index() const; + static device ext_oneapi_from_index(size_t index); +}; +---- +|==== + +''' + +[frame=all,grid=none,separator="@"] +|==== +a@ +[source,c++] +---- +size_t ext_oneapi_to_index() 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()`. + +_Throws:_ An `exception` with the `errc::invalid` error code if this device is +not a root device. + +''' + +[frame=all,grid=none,separator="@"] +|==== +a@ +[source,c++] +---- +static device ext_oneapi_from_index(size_t index); +---- +|==== + +_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 +which has that index. + +_Throws:_ An `exception` with the `errc::invalid` error code if the `index` is +out of range. + +''' + + +== Example + +[source,c++] +---- +#include + +int main() { + sycl::device d1; // Get the default device. + // There is no guarantee this has index 0. + + size_t index = d1.ext_oneapi_to_index(); + sycl::device d2 = sycl::device::ext_oneapi_from_index(index); + assert(d1 == d2); +} +----